API Documentation with Github and Jekyll

Tuesday, October 7th, 2014
By Daniel Miller

A large portion of the Homeflow system is exposed to designers and developers nationwide so they can develop and produce estate agency websites on our platform. We have several apps that work together to produce our sites and one such app is used a great deal by external developers. It’s our front end presentation app, it’s called Ctesius, and it contains all the ‘know how’ to produce a property website from a directory of Liquid, HTML, JavaScripts, etc.

We all know the importance of API documentation, especially as an app grows and as more external developers are introduced to it, so with that out the way…

What we had – Github Wiki

Previously we used a Github Wiki as a repository for the Ctesius documentation. It was good up to a point – you had your main content section then your sidebar that could hash to various sections. As the company and therefore the capabilities of the app grew, more and more content had to be added to the Wiki, which soon started creaking under the pressure. The document was huge – the menu equally so. There was no way we could break it down, there was no way we could improve the menu system or get it to auto update. In short we needed a new solution, one which would give us complete design control and one that would scale with the company.

Github and Jekyll

Github has a neat feature called Github Pages that can take your current Github Wiki and turn it into a themed website. This is ok but wouldn’t give us the flexibility we needed. Even neater, Github allows you to create a repository based on your organisation that you can build a custom site on. Jekyll support is baked right in, so if you create a new project skeleton or download a theme and run it locally, you can start to build up your site. Note that Jekyll is a Rails app so you’ll need Ruby and Rails installed.

Going Freelance(r)

To get going we acquired the Freelancer theme. Freelancer is a nice, flat and responsive Bootstrap theme that we used as a basis for our development. There are stacks of other themes available, or you can develop from scratch if you like. The goal was to have an end product that would look and respond like our own website.

Structuring the Documentation

Jekyll is powered by a YAML file and what Jekyll refers to as ‘front matter’. After you’ve created your templates, the YAML and front matter tell Jekyll the layout to render the post in and can be used to provide supplementary information such as the category of a post, its title and so on. Our goal was to have some well defined categories that posts would belong to, then allow each category to have its own URL, which would contain a hashable list of the posts. In addition, we needed the sidebar menu to auto populate with new sections and/or posts and for it to know if a section had a sub-menu.

The Solution

Our solution was to employ a set of folders in the root directory that would act as our category page holders. They would only contain an index.html file with some front matter:

layout: section
title: Property searching
modal-id: property-searching
category: property-searching

So when someone would access the Property Searching page (/property-searching), Jekyll would use the section layout (layouts are in the _layouts folder) as well as the other information provided to build the page. Within the section layout, we have a loop:

{% for post in site.categories[{{page.category}}] reversed %}
<div id=”{{post.modal-id}}”>
{% if post.title %}
<h3>{{ post.title }}</h3>
{% endif %}
{{ post.content }}
{% endfor %}

This loop essentially extracts the posts that belong to the page.category we provided. Conveniently our categories and page names are all the same so this is a cinch. Note we’ve reversed the loop. Jekyll enforces posts to have a date and would normally loop through them with the latest one first.

Every site needs an index, so we employed an index.md file in the root of the directory that this time had front matter as well as the index content (all written in Markdown, by the way). The index file uses the default layout, which doesn’t employ a loop but instead just outputs the title and Markdown as HTML.

The Sidebar

The sidebar would need to be included on both the default and section layouts and needed a way of knowing what the page links were, whether the section had a sub menu, the running order of the sections and so on. To solve this we used the YAML file to contain some well defined sections that corresponded to our page names and post categories, here’s the first:

– title: Getting started
id: getting-started
sub: true

This allowed us to loop through the sections, then use the section.id to loop through the posts within the category. The sub true or false allowed us to output a sub menu as required. With a small bit of JavaScript we could make the menu respond and slide down the sub menu when clicked.

The End Product

Though it continues to evolve, we now have a sound documentation platform that allows us to quickly add new posts using Markdown, push them to the Github repository and go live within minutes. It’s also in our branding and sits on a tidy CNAME: