So, management wants a microsite for blog-entries ASAP, while the techs wants to use tools they are used to - markdown and git. On top of that, we have a limited spare time for implementing a new solution.
In the intersection of that lies Jekyll!
Jekyll is a tool that simply put builds a static blog out of markdown content. Jekyll does not need a database, nor does it need a GUI where you write your articles in order to insert it in said database. Simply use whatever editor you want to create simple markdown text files, then drop the files in a dedicated directory. Publishing the article is done by running the tool, which rebuilds your site in seconds.
Getting started
The Jekyll software is bundled in e.g. the Ubuntu distribution. In order to get the latest version, you can use the ruby package handler, gem. Install Jekyll, and let Jekyll bootstrap a site for you:
gem install jekyll
jekyll new my_site
cd my_site
jekyll serve
This will install the software, bootstrap a vanilla site in the my_site directory and start a webrick server serving the site on http://localhost:4000 .
Jekyll now recommends using bundle for this:
bundle install
bundle exec jekyll serve
but you can use of course use the method that works best for you.
Themes
The net offers a plethora of Jekyll theme collection sites, where you can download templates both free and at a cost. Pick a theme, download or fork it. Then enter the theme directory and run bundle exec jekyll serve.
This site used the HPSTR theme as a starting point. This theme is helpfully hosted on GitHub under a BSD license, which leaves it only a git clone away.
This theme has some additional software dependencies which needs to be satisfied:
gem install jekyll-sitemap jekyll-paginate jekyll-gist jekyll-feed
Customizing
When customizing a theme, it helps to be familiar with liquid and SASS. Or you can muddle along with the rest of us.
One of the customizations we did to the HPSTR theme was adding support for showing authors.
In this case, we dumped a YAML file in the _data directory: _data/authors.yml:
larso:
name: Lars Olafsen
title: Operations Manager
desc: "Lars works with IT"
stone:
name: Fredrik Steen
title: Operations Manager
desc: "Fredrik also works with IT"
Jekyll can retrieve this data by either addressing it directly in the template code through site.data.authors.larso, by setting an additional reference variable in e.g. an article header:
----
author: larso
----
In a template file, we can now add code that looks up the correct data block using a for-loop, then uses the associated content:
{% assign author = site.data.authors[page.author] %}
{% if author %}
<p><b>{{author.title}}</b></p><p>{{author.desc}}</p>
{% endif %}
Now keep gold-plating that site!