Turn your github documentation to eleventy.

4 min readJun 6, 2020

The success of your open source project and indeed any complex solution depends on good documentation. Writing documentation can be a real challenge, especially if you are too involved with a project from its inception. Knowing every detail you may fail to explain what is obvious to you and your team. In this article I want to discuss the technical aspects of documenting a GitHub repository.

Our project being an open source API and library for spatial data interfaces.

GEOLYTIX/xyz

Open source presentation, controller, domain and service layers for spatial data and application interfaces. The XYZ…

github.com

GitHub Pages — keeping it together

Being Open Source in nature we only considered free hosting options. The documentation should also be a part of the code repository itself. GitHub Pages are therefore the ideal solution for our needs. Within minutes the master branch can be hosted through a CDN; SSL certificate, meaningful URL, and batteries included.

While being able to assign a custom domain, we believe that the organisation @ github.io and the repository name as first URL path segment are already a great address for any documentation.

Building from the repository’s master branch also allows access to any of the incorporated resources via GitHub Pages as a CDN.

What’s left to do was to create a /docs directory full of compiled documentation pages.

Eleventy — static site generator

Written in Javascript, our programming language of choice, 11ty became quickly our favourite static site generator. With a minimum of feature bloat and dependencies, 11ty ticked all the boxes. We instantly liked the ease of configuration for a tool which turns markup into static web pages.

A single html root template provides us with a responsive grid view to include navigation as well as content compiled from markup documents.

11ty was installed as a dev dependency since it is not required to deploy the compiler with the XYZ API itself. The html root template and individual markup documents are stored in the eleventy folder.

The eleventy package can be executed using npx:

npx eleventy — input ./eleventy — output ./docs — formats=md

This command would take all markdown files from the input directory and compile static pages with the provided root template in the output directory.

Tree view navigation

The XYZ API and library structure closely follow the organisation of javascript code in the repository. It was desired to have a tree view navigation for the documentation to be compiled from the organisation of markdown files in the ./eleventy input directory.

This was achieved with 11ty front-matter data and the .eleventy configuration.

---
title: XYZ
tags: [root, getting-started, workspace, develop, mapp]
layout: root.html
orderPath: /_index
---

The front-matter allowed us to provide tags which should be shown in the tree view navigation and fine tune the order of documents. We did not want the order to be alphabetical alone. Certain articles are meant to be the first in a group. Prefixing the file name with an underscore in the orderPath would ensure that this article would be sorted ahead if compared with a regular filePath. The collection sorting was handled in the .eleventy configuration.

Furthermore we want to make sure that subsequent articles in a branch would be indented in the tree view. This would require some css to be derived from a level property. The base level could be derived by splitting the path on slashes. The penultimate element in the resulting path array being the branch. While iterating through the sorted collection of articles we store the current branch and reset the level by 1 if the branch changes, thus providing that the first article in a branch would have a superior level to its leaf articles.