Working with our documentation

Documentation

You will find the documentation here.

Find the Architecture Decision Records in the ./adr folder

Rendering

We use Hugo for page generation, we keep the configuration in the /.pages folder and then we have our documentation here as Markdown.

You can install Hugo with brew brew install hugo and then run the following commands:

# Fetch themes
git submodule update --init --recursive
# Run server
hugo server --source .pages

And then it should run a website on port 1313.

Hugo allows for regular Markdown documents to be turned into a website, for example this document can be found at localhost:1313/.

Formatting documents for Hugo

Hugo introduces two “special” constructs in Markdown. Shortcodes and Front Matter.

File structure

Each Markdown document becomes a webpage available at the corresponding path. Each folder becomes a “top-level” page with an _index.md to control the contents. The theme describes it here.

Front Matter

A “Front Matter” is simply some YAML-based metadata about a page enclosed in ---, for most pages all you need to specify is a title for example:

---
title: "Example"
---

Some Text Here

However, the Theme we are using has a special “Chapter” construct that are suited for top-level pages with sub-pages beneath it.

---
title: "Example"
chapter: true
pre: "<b>4. Examples</b>
---

Some Text Here

Shortcodes

In Hugo a Shortcode is a piece of logic you can inject:

Some text {{< gist spf13 7896402 >}}

The “logic” is simply a templated HTML snippet that can use Hugo’s more expressive functionality. We can create our own of these if we want to, but Hugo and the theme both have a good selection available.

Referencing images

All files in the docs folder will be available as static files, so if you add an image at /docs/example.png you can reference it in Markdown as ![example](/example.png).

Diagrams

Our theme supports Mermaid out-of-the-box for small inline diagrams.

On top of that, we have created a custom ShortCode to render Draw.io diagrams:

{{< drawio src="example.drawio" >}}

And one for PlantUML:

{{< plantuml src="example.puml" >}}

The theme

We are using Relearn which has a lot of features and a very good documentation which not only described the theme itself, but also more fundamental issues like Markdown Syntax.