The purpose of this post is to document what I’m using to run this blog (and thus serve as some kind of prompt when I’m trying to fix stuff in six months’ time) and hopefully also help you set up your own blog.
I use GitHub Pages to host this blog. If you’ve never heard of GitHub Pages before, it is a completely free static website hosting service provided by GitHub. As you might expect with something coming from GitHub, each site is backed by a Git repository (mine is charleskorn/charleskorn.github.io, for example). This means you instantly get things like version history, backups and offline editing with zero extra effort.
You can use GitHub Pages to create a site for a user (which is what I have done for this site), a single repository or an organisation. More details on the differences are explained in the help area.
You can use it to host purely static content, or you can have your final HTML generated by the Jekyll static site generator, which is what I use. As soon as you push your changes up to your GitHub repository, all the static files are automatically regenerated within a matter of seconds.
With Jekyll, you write your posts as Markdown files, and then it generates HTML from your posts based on templates that you define. It also has built in SASS and CoffeeScript compilation, RSS feed generation and support for permalinks, amongst other things. It’s also straightforward to set up a custom 404 page.
Side note: as you can imagine, some features of Jekyll are restricted by GitHub. For example, there is
a limited set of allowed plugins, but by and
large, you can use the full functionality of the core Jekyll project. If you need more flexibility, you can always generate
the pages yourself and push the result up to a branch called
or just turn Jekyll processing off altogether.
(We use this technique for the ThoughtWorks LevelUp website, for example.)
The final missing piece of the puzzle is setting up a custom domain name
to point at the site hosted by GitHub. This is fairly straightforward to do. It requires
in the root directory of your repository with the domain name you’d like your site to use
(you can see mine for an example),
and then configuring your DNS server to point at GitHub’s servers.
My writing process looks something like this at the moment:
bundle exec jekyll draft "My cool new article"
bundle exec guard
- writing, checking a live preview in my browser
- more writing
- editing and proofreading
bundle exec jekyll publish _drafts/my-cool-new-article.md
git commit -m "My cool new article"
Not all of this is built in to Jekyll:
jekyll draft and
jekyll publish commands come from a handy plugin called jekyll-compose.
They don’t do anything you couldn’t do yourself –
jekyll draft just sets up the scaffolding of a draft post and
jekyll publish just
moves that post into the
_posts folder and adds the date to the file and the front matter
– but they certainly make things that little bit easier.
I also used the opportunity of setting up this blog to learn about some standard SEO practices for websites (given the topic sometimes comes up in my day job).
The next step was adding an XML sitemap, which helps search engines discover all of the pages on your site. This is can be generated for you as part of the Jekyll build process by the jekyll-sitemap plugin.
However, simply generating the sitemap isn’t enough – you also need to tell Google about it. You can use Webmaster Tools to do this instantly, or list it in your robots.txt and Google’s crawler will pick it up next time it indexes your site. Furthermore, when the content on your site changes, it’s a good idea to ping Google to let it know. I have a Travis CI job set up to do this automatically whenever I push changes to GitHub. (This also checks for simple issues like broken links and malformed HTML using html-proofer.) It’s a similar process for other search engines as well.
Another thing that I’m not 100% sold on the value of is schema.org markup. The idea is that you decorate your
HTML with extra attributes that describe what their content means, for example, that a
span contains the author’s name, or that
h2 is the blog post title. It enables some of the extra information you sometimes see next to search results such as the date the
post was written and the author’s name, but I’m not sure how much it helps with people actually finding content relevant to their query.
(Although I’m sure that if Google told us that it did impact search ranking, you can bet that it would be exploited within hours,
diminishing its usefulness somewhat.)
This turned out to be much longer than I expected… I hope you found this useful (even if this is just Future Charles reading this).