Starting your blog on GitHub Pages

Aug 16, 2016

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:

Create a repository

Clone it

Commit a simple file

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:

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.