Writing guide

This document is meant to be read alongside the style guide to provide concrete examples on formatting the document and syntax of different Hugo shortcodes.

Documentation overview

All Dolittle documentation is generated using Hugo 0.58.3, with the Dot theme.

Writing documentation

Metadata

All files MUST have a metadata header at the top of the file following the Hugo Front Matter format. Some of this metadata gets put into the generated HTML file.

The keywords and title properties are used for searching while the description shows up in the search results.

---
title: About contributing to documentation
description: Learn about how to contribute to documentation
keywords: Contributing
author: dolittle
// for topmost _index.md files add the correct repository property
repository: https://github.com/dolittle/Documentation
weight: 2
---

The main landing pages also have an icon attribute in the Front-Matter. These icons are from the Themify icon pack.

Documentation filenames

All files MUST be lower cased, words MUST be separated with a dash. Example: csharp-coding-styles.md. Hugo also takes care of converting between dashes and underscores as well as lower- and uppercase.

Links

Within the documentation -site

When adding links to other pages inside this site you need to refer to the page file-name without the file extension (.md). Also, you cannot use the “normal markdown” link [text](filename), you need to place the filename inside `{{<ref “filename”>}} - otherwise the link will be broken. For instance, linking to the API documentation is done by adding a markdown link as follows:

[API]({{< ref "api" >}})

Renders to:

API

External resources

Linking to external resources is done in the standard Markdown way:

[Dolittle Home](https://github.com/dolittle/home)

Looks like this:

Dolittle Home

Diagrams / Figures

Hugo supports Mermaid shortcodes to write diagrams. Mermaid SHOULD be favored over using images when possible. Mermaid documentation

flowchart TB
    Understand --> Describe --> Understand
    Describe --> Implement --> Understand
    Implement --> Verify --> Understand
    Verify --> Deploy --> Understand
    Deploy --> Operate --> Understand

Some diagrams/figures might not be possible to do using Mermaid, these can then be images. Beware however how you create these images and make sure they comply with the look and feel. Also remember to add alt text to all images explaining them for screen readers.

Images

All images should be kept close to the markdown file using it. To make sure the folders aren’t getting cluttered and to have some structure, put images in a images folder.

Images should not have backgrounds that assume the background of the site, instead you SHOULD be using file formats with support for transparency such as png.

<repository root>
└── Documentation
    └── MyArea
        └── [markdown files]
            └── images
                [image files]

To display images use the standard markdown format:

![alt-text](../images/dolittle.png)

Renders to:

Notices

Hugo supports different levels of alerts:

Tip

Use tips for practical, non-essential information.

{{% alert %}}
You can also create ReadModels with the CLI tool.
{{% /alert %}}

Renders to:

Warning

Use warnings for mandatory information that the user needs to know to protect the user from personal and/or data injury.

{{% alert color="warning" %}}
Do not remove `artifacts.json` if you do not know what you're doing.
{{% /alert %}}

Renders to: