If you’re a developer and you think about starting a blog, think no more. DO IT! I recommend you to go the same way I did and friends of mine did too. Start with github pages. In this article I’ll show you how did I start and how does this relate to my previous entry on running a Jekyll with Docker.

This entry is focused on the way I have set it up so it’s easy for you to follow. On any level there are tons of options how you can change or customize your workflow, but I reference only few of them. That’s because I want to get you started quickly. In case you have any problems, leave a comment below. I’ll help you and our conversation may help others too.

What is GitHub Pages

GitHub Pages is a platform for hosting sites using github repositories. You don’t need any server, web provider, DNS settings, databases and configuration. GitHub Pages covers all for you. It does so by hosting static files from your GitHub repository on their own infrastructure.

There are two flavours of GitHub Pages - user/organization sites and project sites. For your personal blog I recommend a user site. There’s great tutorial at GitHub Pages, please follow their 4 simple steps:

  1. Create a repository
  2. Clone it
  3. Commit a simple file
  4. Push it

And you’re done. You can write your first content using any editor. You can even use the GitHub web-editor, so if you’re thinking about your blog, think no more. DO IT!

Use Jekyll

Keeping it all as static files is tedious in the long run, and you may (should!) start looking for a way to automate this. I highly recommend Jekyll.

If you don’t know what Jekyll is please visit their site or read my previous entry. It’s a static site generator, that creates sites from documents, that you can write in plain text files with Markdown syntax.

When using Jekyll you can forget about HTML and just write the content. If you have something on your mind you would like to share with the public, just write, commit, push. And in case you wish to check how does it look like when generated by Jekyll, run it on your machine first. I recommend running it in Docker container as I described in previous entry.

GitHub Pages variant of Jekyll

There are some limitations that GitHub Pages places on all Jekyll based sites. Some settings have specific default values and others you’re not allowed to change, more info here.

It’s probably best if you could run the same or similar setup on your machine. If you’ve followed my previous article, then it’s as simple as changing to different Docker image. I have set up another alias in my PowerShell startup script that looks like this:

function ghpages{
  docker run --rm --label=ghpages --volume=$(pwd):/usr/src/app -it -p :4000:4000 starefossen/github-pages
} 

Now instead of jekyll serve I run ghpages serve and it works too. In fact that image has force_polling enabled by default, so there is no need to supply that as environmental variable.

Caveats

There are some issues I have ran across that I would like you to know about.

GitHub Pages cache

When you push your change to GitHub repository, changes you made may not be instantly visible. Don’t panic, wait for it. GitHub Pages may keep a cached version of your previous site and just allow a few minutes for that cache to invalidate. There’s no need to frantically refresh. It caught me when I was experimenting with new repository and editing files using GitHub’s web editor.

Jekyll excerpts on Windows

Jekyll has a nice feature: Post excerpts. It can use beginning of the post article as an excerpt, for example to show it on the index page.

An excerpt is automatically defined as first block of text up to the excerpt_separator sequence. It’s default is \n\n - just two newlines. Since I’m running on Windows it didn’t work for me, and I changed it to \r\n\r\n - two newlines “the Windows way”. It worked locally, but failed when I pushed to GitHub. That’s because my repo has automatic EOL conversion, it was changed to \n\n, and then GitHub Pages engine rendered that using environemnt, when the reverse conversion did not happen, and the excerpt_separator was finally not found.

To overcome this I decided to include <!--MORE--> HTML comment in my article bodies as the separator. Works reliably.

Final words

DO IT! No, really, if you were ever thinking about it, then do it now. It should take you 30 minutes. Even if you don’t want to publish now, just experience how easy it is and feel empowered.