I recently decided to start a blog. I had a few criteria:
- free hosting
- free custom domain support (to host it on blog.thecoderecipe.com)
- good support for embedding code in posts
- simple yet modern design
After experimenting with various “ordinary” blog platforms (e.g. Wordpress, Blogger and Tumblr), I discovered GitHub Pages and Jekyll.
In short:
- GitHub Pages lets you host static websites for free
- Jekyll lets you generate a blog from static Markdown files
- GitHub Pages supports Jekyll out of the box
Here is what I had to do to set up this blog.
Set up instructions
These instructions were last tested on 30 November 2015. Let me know if you encounter any problems.
Install Jekyll and create the blog structure
The following assumes that you have Ruby 2.0 and RubyGems 2.0.14 installed.
# Install Jekyll and other gems that GitHub Pages uses.
gem install github-pages
jekyll --version
# jekyll 2.4.0 (should match https://pages.github.com/versions/)
# Ask Jekyll to create a new blog directory for us. Let's call it 'myblog'.
jekyll new myblog
# Create a Git repository
cd myblog
git init
git add .
git commit -m "Initial setup"
# Important: use a branch named "gh-pages". Alternatively, you can use the
# master branch if your Git repository is called 'yourusername.github.io'.
git branch -m gh-pages
# Create the 'myblog' repository on GitHub so that you can push to it.
# See https://help.github.com/articles/creating-a-new-repository/.
# Set up the origin.
git remote add origin git@github.com:yourusername/myblog.git
git push origin gh-pages
Test it out
You should now be able to access the blog at https://yourusername.github.io/myblog/. You’ll notice that it looks terrible: the CSS isn’t loading!
That’s because you need to customize _config.yml
, and more specifically the baseurl
field. If
you intend to leave the blog at that address, you should fix it.
However, if you are going to use a custom domain, you can leave it as is—it will fix itself soon.
Add CNAME and configure your domain
Ignore this if you don’t want to use a custom domain such as http://blog.yourdomain.com.
In the following, we assume that you want to use http://blog.yourdomain.com to host your blog. Note that the subdomain you use does not need to match the name of your Git repository (it doesn’t have to be called “myblog”).
# In the myblog directory, add a CNAME directory with your intended domain.
echo "http://blog.yourdomain.com" >> CNAME
git add CNAME
git commit -m "Use a custom domain"
git push origin gh-pages
In your domain provider’s DNS zone file, add a CNAME alias from your subdomain (e.g. “blog”) to “yourusername.github.io”.
Finally, try loading http://blog.yourdomain.com. You may need to wait for DNS changes to propagate
(up to an hour). If you see CSS-related errors, make sure that your baseurl
config is empty.
Update your config
Now that your blog is live, you can customize it as you wish. You will want to edit the following files:
_config.yml
(e.g. blog title and summary)about.md
(about page)index.html
(index page)_posts/*
(where all your blog posts live)css/main.scss
(CSS style)
You can easily preview your changes by running jekyll serve
from your directory. If you update
_config.yml
, you may need to restart the server to see your changes reflected.
Troubleshooting
Here are various mistakes I made along the way:
gem install jekyll
instead ofgem install github-pages
(wrong version)- forgot to update
baseurl
in_config.yml
, resulting in a failure to load the CSS
If you’re curious, you can find the code for this blog on GitHub. You may especially be interested in the first commits.
I hope this helps!