Jekyll vs WordPress
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
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 http://127.0.0.1:4000/
Layouts
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 %}
Minima
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 jekyllrb.com 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.