Working with the guide

Rendering

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

You can install Hugo with brew brew install hugo and Go with brew install go 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.