Jekyll sites consist entirely of static pages. No scary database or code execution. This makes Jekyll very portable. The site folder can easily be copied as a backup, or placed on a new web server and re-hosted. All the blog posts are text files, making it is easy to copy a similar post and inherit the layout or structure.
Jekyll is a product of the same team that developed Github and it can be hosted on a Github account. At first I didn’t see this as a must have but over time I’ve become a convert. Many of the things I’m inclined to write about involve code or documents that are evolving. All the stuff one would host on Github.
Each repository supports a special branch gh-pages that serves project based documentation, independent of your other repositories. Each Github account is also allowed a site-wide Jekyll instance that can be linked to your own domain name. That’s where this page is hosted. The nice thing about this approach is that your documentation follows your code and is backed up and replicated along with it.
Jekyll installation
I found the easiest way to get an account-wide Jekyll up and running is to follow Github’s own instructions at Jekyll Installation. A site-wide Jekyll instance can only be hosted from the master branch of a repository that is named <account name>.github.io. No other repository or branch will work for a site-wide presence. I created the repository using the Github web interface.
The instructions begin with a local PC based installation and I eventually settled on a directory structure ...\sites\koziniec.github.io to match my Github repository and account URL. As I add project based sites I’ll include the repository URL under the sites directory.
I cloned my empty https://github.com/koziniec/koziniec.github.io into my local folder and then followed Github’s CLI installation instructions. Ultimately you push the installed files up to Github where they are immediately (well maybe a couple of minute later) available from koziniec.github.io.
Visiting the settings wheel for the repository allows you to link your own domain name after adding an appropriate CNAME entry. In my case www.koziniec.com points to koziniec.github.io. The settings page also provides an indication as to whether your site is up and if not, what the problem might be.
Adding the So Simple theme
Once the basic Jekyll siteis running you can change themes easily from within the settings page. However, you have only a limited range. I settled on the very minimalistic although ironically named So Simple theme available via Github. I really struggled to get this installed by cloning the repository and various other approaches. Late last year I struggled with it as well and always seemed to get an issue relating to a missing Rake Gem.
My final “So Simple” install success came via the Github pages method which seems to be a built-for-purpose theme management tool as opposed to the more general “repository” approach.
Anyway, I’m happy with the result and a little intrigued that in recent weeks I’ve independently crossed paths with:
- Github
- Jekyll
- Atom (Editor and IDE)
All of them turned out to trace their roots back to the same developers. That made me curious about their other endeavours and then I stumbled on https://blogs.microsoft.com/blog/2018/10/26/microsoft-completes-github-acquisition/
:-)