Create and host a static website on Github Pages with a custom domain.
Hi all! I’ve heard a lot about static page generators before but actually didn’t use them much. And lately I’ve decided to create a website using one of them (I took Jekyll) and host it on GitHub Pages with a custom domain. I knew that it should be possible. And it is possible and quite easy by the way. I found a few how-to articles what helped me to quickly understand how this process works. And now I would like to summarise those tips and add more from myself on top of the stack.
What is GitHub Pages
GitHub Pages uses one of the most popular static website generators which is Jekyll. It means GitHub will compile and serve your website from source code to HTML/JS automatically.
If you create a repo for your website inside of a GitHub organization the link will look like
Let’s say you’ve created a repo on GitHub and you want it to be a website. For doing this you just need to activate a GitHub Pages feature for this repo. Go to its settings and search for that section:
As you can see you can choose a specific branch which will be used as a main branch for the website, theme and also specify your custom domain there.
Choose a theme
I played a bit with Theme Chooser and figured out that I can either create my website from scratch (for instance, find some 3-rd party Jekyll theme and install it manually) or choose one of the pre-installed themes from GitHub. I’ve chosen the first option but probably you will find some good theme for you from pre-installed ones. It will a be even easier and faster to create a website in that case.
Apply a custom domain
I assume that you’ve already purchased a domain. Now it’s time to connect it with our website hosted on GitHub Pages. You need to specify the domain here in repo settings but also you need to change your domain’s DNS records. Every domain registration service should provide an interface to configure DNS records. Just log in there and change domain’s records to point out to the GitHub servers. You need to have at least one (or better two) so called
A Record pointing to following IP addresses:
188.8.131.52. And also recommended to have one
CNAME Record for www alias, pointing out to the
<your-username>.github.io. In case of organization it’s still a bit unclear to me how to better handle
CNAME Record. For now I set it up as
<organization>.github.io (because it doesn’t allow to use
/ to specify whole URL) and it actually works so far and website with
www are getting redirected to the main website (without
Here is how DNS records look like for my domain:
Also, ensure that your repo contain
CNAMEfile which should contain your domain name inside.
Develop and test website locally
As I mentioned above GitHub Pages compile the source code to HTML/CSS/JS automatically using
Jekyll every time you push/merge your changes to specified branch. But how to test your changes locally and develop website? Right, you need to install
Jekyll locally for that.
Prepare a local environment (tested on Mac OS X):
Handle project dependencies
I had not much experience with Ruby infrastructure in my past, so it took me some time to figure out how to save and install dependencies. After a short research I’ve found a Bundler, it responsible exactly for this.
All the dependencies (in Ruby world they called
Gems) are stored usually in file called
Gemfile. If you don’t have a
Gemfile in your repository you can create it by running the following command:
bundle init. Then you can add a specific dependency by running
bundle add <GEM-NAME> or install all the dependencies from
Gemfile by running
Run website locally
Now when you installed all the dependencies you can easily run your project locally by following command:
jekyll serve -w (
-w flag is responsible for watching and auto-rebuilding the project after any change). This command will compile and run your project on your localhost, it should be accessible on this URL:
Also if you don’t want to host your website on GitHub Pages, you might use command
jekyll build to build your website. It will compile website without running local web-server.
Here is more-less everything what I wanted to talk about today. I’m still playing with
Jekyll and it looks interesting so far. If you have anything to add please don’t hesitate to leave comments. Cheers!
I’ve found that Chrome starts marking all HTTP sites as “not secure” at the moment. That means it’s time to think seriously about SSL certificate for your website. The great news is that GitHub Pages started supporting HTTPS for custom domains out of the box recently. And it’s super easy to make it happen.
If you already have your custom domain is attached to the repo without HTTPS support what you need to do is to change A Records for your domain. You don’t need those two A Records added above, they can be removed. Instead of them you need to add new A Record pointing out to another “https” IP address. You can pick up one of these IPs:
As you remember changes can take up to 48 hours. Then you need to remove your custom domain in repo settings, save and then re-apply. And don’t forget to mark “Enforce HTTPS” checkbox under the domain name input.
If you’re stuck with some problem on this step please check GitHub troubleshooting page.
As you see, getting HTTPS on GitHub Pages is extremely easy now! Just do it! :D