Our last post was about migrating from WordPress to Jekyll. Although the engine is pleasant and has a great design, the main benefit of the move is actually something else.

Of course, we’ll need blog hosting services before we can start writing anything.

Hosting

One of the many features of Jekyll is that it eventually generates simple HTML and CSS files. This means that you will be able to use any web server to host the site. The ruby part is only used at build time. Take the content of your _site folder and upload it. This is a simple task, but will still require a server and a deploy procedure (it may involve keys or passwords and yes, “upload this folder using SFTP to that server” is a procedure).

GitHub offers a nice alternative as GitHub Pages. GitHub Pages allows you to serve any static website or a Jekyll site. For this case, just push the Jekyll source files and GitHub will build the site for you (running the equivalent of a Jekyll build and serving the resulting files).

Basically, any repository can host a GitHub Pages site. These are some of the things that you should know:

  • If the repository’s name is identical to the user or organization name, the default branch is master (user or organization pages).
  • If it is not, the default branch is gh-pages (project pages)
  • While GitHub hosts the site, you’ll be unable to use any plug-in and Jekyll will always run in safe mode. Should you need a plugin, remember you can always decide to build the site yourself and then upload the generated _site.
  • Nothing prevents this repository from being private. Our blog content is public, but our discussions around them are probably best kept inside the company.

We went for a private repository using project pages because we like our blog repository to be named “blog”. Staying with the GitHub defaults for Jekyll was not really blocking for us. It provides a nice perk: a very convenient development and deployment workflow.

A developer’s workflow

As a developer, I’m used to a certain kind of workflow when developing PullReview. I want the same when blogging too.

The good news is that Jekyll & GitHub Pages allow exactly that.

Writing drafts

Like most people, we do not write our posts in a single stroke of genius. More often than not, it entails writing, then going through an internal review cycle, and possibly sending the information for translation and proofreading. This makes a “draft” status very important.

I discovered the option of creating drafts in Jekyll. Any file you put into the _drafts folder will never be shown on production, but it can be displayed locally by launching your blog using the following command:

jekyll serve --drafts 

A date will then be generated and the post shown with the other ones already published. After the review is complete, copy the file to the main _posts folder to publish it. I was a bit puzzled by the absence of an automated conversion from draft to post (something like Jekyll publish _drafts/my_post.md). However, I actually found a better way before I could investigate.

Feature branches

As seen above, anything pushed on the gh-pages branch will be published in production, but anything on any other branch will not. This means that I can create a draft with two simple commands:

git checkout -b feature/blogging-development-cycle 
touch _posts/blogging-development-cycle.md 

I can then start writing, committing or pushing without consequences to the production. Any external material such as images can be added to the branch the same way. While writing, don’t forget the “–watch” option that forces Jekyll to reload the site with every change:

jekyll serve --watch 

Review

The review step was quite easy after starting that way. I just created a PullRequest on GitHub for my post when I felt it was ready, allowing Christophe to chime in:

Poetry

(Of course, complaining about my usage of poetry).

Publish

Having got the review I needed, I can now publish the post by simply merging it into the gh-pages branch. The blog is updated after a few seconds.

A blog engine for developers

The settings of Jekyll & GitHub allow me to get back to the cycle I know and love: Create branch, work on it, make a PullRequest when ready and publish it with a simple merge.

This is exactly what we do for PullReview.