Getting started with GitHub Pages: the unbelievably quick and easy guide for creating and publishing a free portfolio, blog, or website
(This article first appeared on Towards Data Science)
GitHub Pages has to be the coolest tool that people don’t know that they already have. Pretty much any repository on GitHub can be turned into a website with the click of two buttons.
Do you need an online portfolio of your work for potential employers to check out but you don’t know how to make a website? Do you want to create a blog or a business site but you don’t know where to start? Is it possible that you just don’t want to deal with (or pay for) website hosting, domain names, and everything else?
This one’s for you!
Why should I have a website?
It’s hard to imagine anyone who wouldn’t benefit from having a website! You might need to display your portfolio for potential clients or employers. You might need to organize your projects in a way that you can share. You may want to create a blog about the things you’re doing or the places you’ve been. You might need to advertise yourself or your business or sell a product. Whatever your reason, there’s a good chance that you want to put something together without spending a ton of time on it. There’s an even better chance that you don’t want to spend a lot of money.
A website is a way to connect with the world and it’s a powerful tool for communication. It’s a way to share your work, your interests, and your passions. It’s how you can create, build, and control your online image. Plus, the sooner you build your site, the more time you’ll have to build your online presence and reach the people that you want to reach. It can help you stand out in a sea of competitors.
It’s also not the easiest thing to create if you don’t know what you’re doing!
There are a few ways that a beginner can create a simple and completely free website. The main ones are GitHub and WordPress.
WordPress is great for beginners who need all the help. I love WordPress! That’s how I got started with my very first blog! The thing about a free WordPress site is that it’s really obvious that it’s a WordPress site. You have an address that ends in wordpress.com and a WordPress logo at the bottom of every page.
If you’re getting started in the tech world, you’re going to find that you look more appealing if you know how to use GitHub. If you’ve been in the tech world for a little while now, there’s a very good chance that you already have somewhere between one and one million repositories on GitHub right now.
Why not build your website on GitHub and host it right from your repository?
So much of what matters in the tech world right now is contributing to open source. Sharing your work openly in the community is a big deal. GitHub is designed for exactly this. Putting your work on GitHub shows that you’re involved and aware. (I host my portfolio right from a repository on GitHub if you want to take a look. It’s pretty out-of-date, but it is an example of a profile site built with Bootstrap and hosted from a GitHub repo.)
When you share your projects on GitHub, people can see your code, what you’re doing, and how you’re doing it. GitHub is all about the communication of ideas.
Pretty much everyone in tech right now is using Git and/or GitHub in some way. Having your profile right there on GitHub is a great way to hold up your hand and get involved. Plus, you’ll wind up with a repository and some commits on your profile page!
If you’re brand new to everything Git, you might want to check out “Getting Started with Git and GitHub: the complete beginner’s guide.” That article will walk you through the basics of what Git and GitHub are, concepts like “repositories,” and a ton more. I’m going to assume that you already know the basics. If you don’t, it’s worth taking a few minutes to get acquainted with them.
Let’s get this party started!
There are two ways of getting started with your website. You might be starting completely from scratch! On the other hand, you might have a website that you’ve already put together, but you don’t know how to use GitHub to turn it into a free website.
I’ll start with option 2.
I have the files, but I don’t know what to do with them!
This couldn’t be easier. Seriously! GitHub does the rest of the work for you. I’m assuming that you already have a GitHub account and that you know what a repository is, but if you don’t, check out that getting started with Git and GitHub article.
In a nutshell, a repository is where your project will live. It’s where you’ll organize your project. You’ll keep folders, files, images, videos, spreadsheets, Jupyter notebooks, data sets, and anything else your project needs in your repository.
If you haven’t already, go ahead and initialize your project with a repository, or create a new repository and upload your files. If you have a file called “index.html” GitHub will already understand what you want to do.
Now you’re going to take advantage of GitHub Pages. Go to your GitHub repository and click “Settings.”
Scroll down to “GitHub pages.” You’ll see this:
Now drop the “Source” dropdown menu to either “master branch” or “master branch/docs folder.” Here’s the thing: if you want to publish from your “docs” folder, you seriously need to have a “docs” folder in your master branch from which you want to run your website!
Chances are, if you’re a beginner, you’ll choose “master branch,” which just means that you want to publish your repository pretty much as-is. (There have been a couple of times where I needed to tweak a file path or two, depending on how I had my folders structured.)
You’re going to see a notification that your site is ready to be published.
Be patient, wait a minute or two, and then refresh the page or try the link if you want. Once your site has been published, you’ll see this:
Try clicking on that link.
Poof! You have a free website!
Now for the other option:
I don’t even know how to get started!
I’m going to tackle things like Bootstrap and basic website design another time and focus on the absolute basics here. I do want you to know, though, that the world is your oyster! The only thing limiting your options here is your drive to make it happen. (Well, maybe drive and also the amount of time you have available…) Because this option is for the complete beginner, I’m going to show you how to do everything right on the GitHub website.
We’ll go ahead and create a new repository first.
Fill in your repository name, a short description, check the box that says “Initialize this repository with a README,” and then click “Create repository.”
Now go to “Settings” near the top right-hand side of the screen and then scroll down to the “GitHub Pages” section. Drop the dropdown menu that says “None” to “master branch.”
First, you’ll see this:
Wait a minute or two, and then you’ll see this:
Now click the link!
You have a website! Congratulations!
That doesn’t look like much
Okay, that does look pretty boring, but you can see here that what’s displaying is your README file.
If you want to make some quick changes, you can go ahead and edit your README to display what you want people to see. To do that, go back into your repository, click the little pencil icon on your README file, and make it better!
You’re using Markdown, and there are a lot of things you can do with markdown files. This includes adding text, images, links, colors, and some basic formatting. It’s a seriously simple way to start! Here’s the Markdown Guide to basic syntax for anyone who hasn’t worked with it before.
(Remember that if you add any images to your README, you want to make sure to upload them to your repository, or GitHub won’t know what you want!)
Now go back to your website and see what you have!
Be aware that it sometimes takes a few minutes for the changes to go through. If you don’t see your changes immediately, wait a few minutes and try again. I’ve also had an issue where my laptop wanted to keep going back to an older version of my website even though I’d made changes. Deleting my browser history for the last 24 hours fixed that problem. Try the easy fixes before you freak out about the complicated stuff!
That’s an improvement, but it could be more interesting
If you’re a total beginner and you don’t know anything about CSS, but you want a little more visual appeal, try a Jekyll theme! They’re prebuilt themes that you can use to make your site look a little better with basically no effort on your end. Jekyll and GitHub will do the work for you! Your job is to push a button or two.
Go back to the “GitHub Pages” section in “Settings” and click on “Choose a theme.”
Let’s see what our website looks like if we choose the first theme that shows up. All you have to do is press the green “Select theme” button, give it a couple of minutes, and then try your website again!
And with just a few minutes of effort, we’re already getting somewhere!
That’s it! In just a few minutes, you created your own free website for your business, blog, or portfolio, hosted it through a GitHub repository, and it’s already up and running. You’re ready to share with the world!
Way to go!!!
Just a couple of notes:
* If you decide that you don’t want to use a theme after all, there’s no button to go back to the original version. It’s actually totally easy to get rid of your theme, though! If you go back to your repository, you’ll discover that you now have a file called “_config.yml” which contains your theme information. If you delete that file, you delete the theme!
* If you want to play around with your theme and theme options, you’ll find that the “_config.yml” file is your first stop. Now that you know that, take a look at the zillions of other Jekyll options that you have! You can even start with the Jekyll Now theme if you want a simple and already set-up blog. Your options are endless!
I can’t wait to see what you create! As always, if you make anything amazing with this information, let everyone know about it in the comments below or reach out any time on Twitter @annebonnerdata.
Thanks for reading and as always…