How to document your open source

So, SackFix nears completion and I have many ways to publish the docs. WordPress is one, but frankly I’m a little annoyed by it. GitHub pages seems to be the preferred way, but I am doing this to learn, so lets try Jekyll.


Jekyll home The key with google now is to generate mobile friendly pages, and although there is a bug in the menu on mobile I still went for minima… Minima GitHub

Pros of Jekyll

The problem with hosted word press is that you don’t get to backup the content into your own git servers. Its all embedded html, and that is really old school. Also, my hosting company requires that I give the entire site over to wordpress, so you cannot mix and match parts of the site with raw html and others with wordpress. So playing with angular or whatever takes its place need yet another site.

There is a live renderer during dev work for Jekyll and a ‘compile’ cycle prior to upload. All very familiar, since I started out on DreamWeaver pretty much as soon as it came out.

How to actually author the content?

I’ve been using WebStorm for all things html and javascript recently, but that overkill for markdown. Back to notepad++, which will do.

Using Jekyll

As ever the notes below are cribbed from the web, they are for my own use, and act as a memory jogger.

cd \all_dev\websites\jekyll
# Create a new websites
jekyll new sitename
cd sitename
# then start up the sitename
bundle exec jekyll serve


Jekyll supports pages and posts. It impacts the site format and the menu.

layout: page
layout: post

So an example of the page for part of the site is:

layout: page
title:  "SackFix - Scala Akka Fix implementation"
date:   2017-03-18 08:01:49 +0100
categories: Fix SackFix Scala AKKA

Syntax highlighting

Obviously techie sites need code formatting and that is supported

{% highlight scala %}
{% endhighlight %}


This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at You can find the source code for the Jekyll minima theme at: GitHub

Where is the rest

All on the Jekyll github pages. Not much to it, its simpler than wordpress, lets you keep control and version it all on your own git repo.

A few more notes:

config.yml : site wide config Pages in the base dir, use the page header and specify the permalink.

layout: page
title:  "About"
permalink: /about.html

Posts in the _posts dir, but I found I hated the blog post format, I just want a web site that renders on Mobile and isn’t wordpress.

layout: page
title:  "Running the examples"
permalink: /runningtheexamples.html

So where is my site?

It’s no work of art, but it is now up at SackFix.

Maybe sometime later in the year I’ll move off wordpress for this blog…Or in the spirit of training maybe I’ll stay on wordpress.