I’ve been hosting my blog using GitHub Pages + Jekyll combination for about eight months now. I learned some advantages and disadvantages of using these tools, so I thought I should create a guide on how to become Jekyll poweruser (and use GitHub for hosting your websites).
What is Jekyll?
Jekyll is a static site generator that allows you to create a blog or a website without having to worry about complicated administrative tools, databases etc. Jekyll stores everything inside of text files. It allows you to publish your posts using Markdown markup language (we’ll talk about that later). It’s completely free and open source. If you have a GitHub account, you can host your site completely free and have full control. Unlike Wordpress.com, pretty much every theme is free and there are no restrictions on which theme you can use with it. Your blog won’t be serving ads unless you want it to and you can change everything you want to on your site just by having a basic HTML knowledge.
What you’ll need to have/know follow this tutorial
- A GitHub account (obviously)
- A local machine running Linux with Git installed (
sudo apt-get install gitis all you need). You’ll also need to set up your Jekyll environment. I should point out that Jekyll doesn’t officially support Windows, but if you have a Mac, that’s fine too.
- Some basic
bashknowledge (you’ll need to know how to navigate between directories using
- A custom domain (optional)
Things GitHub allows you to do
GitHub allows you to create one custom domain that has to be named
USER is obviously your GitHub username. You can think of it as a central place for your website. If you have a GitHub organization, you can create another URL which will be titled
ORG.github.io. You can also create websites for your specific open source projects which will be hosted at
Note: Everything I say further about user’s website can be applied to organization’s websites as well.
Creating a website for you or your organization
To create your main website (
USER.github.io) you will need to create a repository specifically titled
USER.github.io (note: your username doesn’t have to be capitalized). Then, from the terminal on your local machine, execute this command:
git clone https://github.com/USER/USER.github.io
This command will create a subfolder titled
USER.github.io. Navigate inside of it and create a new file called
index.html (you can create a file using the following command
touch index.html). Now, lets actually write some HTML code. Open up the file in your favorite text editor and type this:
Save the file, open up your terminal one more time, navigate to the
USER.github.io directory and execute the following commands:
git add index.html git commit -m 'Initial commit' git push
These commands will sync your local folder with your website. The first command will add the
index.html file to your project, the second command will commit your changes and set
Initial commit as a message for the commit, and the third line will push those changes back to GitHub.
After this is done, just wait for a couple of minutes and open
http://USER.github.io in your browser.
Setting up a custom domain
Feel free to skip this section if you don’t want to use a custom domain.
Now, if you have your own domain that you want to use, create a new file called
CNAME. In it, just type in your domain. I own a r3bl.me domain, so the content of my CNAME file contains
r3bl.me and nothing else. Note that the
https:// should not go here. After this is done, before you publish your changes, you’ll need to edit the CNAME records on your hosting provider. I’m personally using Namecheap so my CNAME records look like this:
The full content of the
IP ADDRESS/URL field is actually
aleksandar-todorovic.github.io. (pay close attention to the dot at the end which is necessary) since aleksandar-todorovic is my GitHub username.
After this is done, after a couple of minutes, your domain should successfully load the content of the
index.html file we created earlier.
Setting up Jekyll
Now we have the domain set up, it’s time to actually build a Jekyll site. Before doing so, delete the
index.html file you created earlier. We don’t need it anymore.
Now, you have two options: you can create a default Jekyll site by typing
jekyll new . in your terminal after navigating inside of your
USER.github.io directory, or you can just copy the content of one of the Jekyll themes. Two of the best resources for custom Jekyll themes I found are jekyllthemes.org and jekyllthemes.net (note: these are two different sites even though they are using a similar domain).
Now, you need to push your changes back to GitHub:
git add . git commit -m 'Initial Jekyll setup' git push
You’ll notice that the first command is a bit different. This time, we’re not only adding one file, but we’re adding the entire content of that directory.
After you’ve done so, in a couple of seconds you’ll have a Jekyll site up and running on your
USER.github.io or your custom domain and now you can start to customize your Jekyll site.
Customizing your Jekyll site
This part of a tutorial is a bit tricky because the customization is different depending on a Jekyll theme you chose. Usually, it starts by editing the file called
_config.yml which is the most important file in your Jekyll repository. In most of the cases, that’s the place where you should set up things like the name of your site, your site’s description, your social links and a list custom Jekyll plugins.
Before you publish the changes back to GitHub, you can preview the changes on your local machine by executing
jekyll serve and then navigating to
127.0.0.1:4000 in your browser. To terminate the command, just press
Publishing blog posts
To manage your blog posts, you’ll need to know a simple markup language called Markdown. If you’ve ever used sites like reddit or StackOverflow, you already know it! Markdown is pretty easy to learn. It won’t take you more than 20 minutes to learn it. Here are some basics:
- To add a title, just type
# Title of the poston the top of your file.
- To add a subtitle, just type
## Subtitle. To add a smaller subtitle, just add another
#. You can have up to 6
#signs. The more you have, the subtitle will be smaller.
- Adding a link to the text:
[name of the link](http://pathtothelink)
**this text will be bolded**
*this text will be italicized*(you can also use
_this text will be italicized_).
- Adding an image:
![name of the image](http//pathtotheimage)
Now that we got that covered, your posts should be stored in the
_posts subdirectory. To create a new blog post, you’ll need to follow this example:
2015-08-22-new-post.markdown. So, the pattern you should follow while creating a new file should be:
year-month-day-name-of-the-post.markdown. Sometimes, you’ll need to add certain meta tags at the top of your file. Those tags should go right at the top of your file like this:
--- author: Aleksandar Todorović layout: post categories: en tags: - tag 1 - tag 2 - tag 3 --- # Markdown code goes here
The most usual meta tag is
layout: post which tells Jekyll that it’s rendering a blog post. Probably every Jekyll theme comes with a couple of default posts, so refer to their file and figure out which tags you should include.
Publishing a page
It’s a bit different to publish a page than it is to publish a blog post. Lets say that you want to create a page titled
about which will be accessed through
USER.github.io/about. You have two options: you can create a file in the directory of your project called
about.md where you’ll write some Markdown text, you can create a file called
about.html where you’ll write some HTML code, or you can create a new subirectory called
about and create a new file called
index.md. The result is the same: your page will be accessible by opening
USER.github.io/about in your browser.
Creating repository websites
The process for creating a website for your other repositories is pretty much the same with some minor differences.
Lets say that you have some sort of an open source project that became popular enough to need its own website. We’ll call it
awesome, because, well, your project is awesome. The difference this time is that you can’t put your files in the
master branch. You’re going to have to create a new branch called
gh-pages. This time,
git clone https://github.com/USER/awesome will not get the job done. This time, you’ll have to execute the following command to clone your website to your local machine:
git clone https://github.com/USER/awesome -b gh-pages --single-branch
This command will copy the specific branch called
gh-pages and that’s where the content of your website will be stored. After you’ve successfully set up your code, just repeat the commands we already talked about to sync your content with GitHub. After that, your website will be visible at
Now if you have a custom domain and you want to use a subdomain for that website, you’ll need to edit the CNAME records on your domain. Create a new subdomain (lets say
http://awesome.r3bl.me) and point it to the same
USER.github.io. URL. Now, in your
CNAME file, add your subdomain (
awesome.r3bl.me) and that’s it. After a couple of minutes, your website will be available at
Some obstacles you’re going to encounter with
- The code behind your website will be publicly accessible, so make sure not to store any valuable data in your repository. If you need to store some valuable data inside of your repository, you’ll need to upgrade your GitHub account from free to paid and make your repository private so nobody else can access it. Your website will still be accessible, but your repository won’t be.
- HTTPS support is… kind of complicated:
- If you’re using a
USER.github.iodomain, your website is accessible by typing
https://USER.github.io, but you can’t enforce your visitors to use HTTPS exclusively, so you’ll have to rely on them to use the HTTPS version. Maintaining both of HTTP and HTTPS versions of your website was too complicated for me, so I gave up on that.
- If you’re using a custom domain, you can’t buy and use an SSL certificate because it will be issued to your domain, not to your GitHub repository, so your certificate will appear as invalid while accessing your site from any major browser. This can be kind of hacked by using CloudFlare. By signing up for a CloudFlare account (don’t worry, it’s free), you can change the nameservers on your hosting to their nameservers. Then, the traffic between the users and CloudFlare will be SSL encrypted, but the traffic between GitHub and CloudFlare will still not be encrypted. That’s the best thing you can do.
- If you’re using a
[Advanced] Some tips and tricks (in no particular order)
- If you have some string that you want to use regularly, put it in your
_config.ymlfile. As an example, my Twitter account is @r3bl_ and I want to link to it often. I will just add a new
twitter: r3bl_line to my
_config.ymlfile and then put a link to it by typing
[@r3bl_](https://twitter.com/). I could also put the entire link (
twitter: https://twitter.com/r3bl_) to my config file and then use
[@r3bl_]()if I want to.
- If you’re working on an article, but it’s still not finished, you can create a new subdirectory called
_draftsand put those articles there. After that, just move them to your
_postssubdirectory to publish them.
- If you want to ping search engines every time you put some new content to your site, create a
gems: jekyll-sitemapline to your
_config.yml. This will create a sitemap on your site available on
r3bl.blog/sitemap.xmlin my case). This is a third party Jekyll plugin that GitHub supports.
- Create a file called
robots.txtand put every page that you don’t want to be indexed by search engines there. Take a look at the
robots.txtof my blog as an example. To make sure search engines index only things that matter, search for
site:r3bl.blogand make sure to use their webmaster tools (I’m personally using only Google’s webmaster tools and Bing’s webmaster tools).
- If you made some big changes to your site, you can ping Google manually by visiting
http://www.google.com/webmasters/sitemaps/ping?sitemap=http://example.com/sitemap.xml(obviously, you’ll need to replace
http://example.comwith your URL). You can do the same with Bing by using
- You can hack your way into supporting HTTPS by adding
https://r3bl.blog/SOMETHING">to every link that points to another place on your website. Your site will still be accessible over HTTP, but every time somebody clicks some new URL, it will take him to the HTTPS version of the page.
- You can mess around with the look of your posts or pages by editing
- You can customize pretty much everything by editing the files in
_layoutssubdirectories. You don’t have to pay attention to other directories. Here’s the link to an original Jekyll theme called HPSTR that I used while I was creating my blog. Obviously, I made quite a number of changes.