Dolittle Documentation

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, a static site generator.
All syntax is GitHub flavored markdown processed by Blackfriday engine inside Hugo.

Documentation is updated whenever a pull request is approved. This will then automatically trigger the Azure Pipeline to build and re-render the pages.

The documentation uses the Dot theme. We’re adhering to the guidelines and documentation of the theme in combination with Hugos guidelines. Get familiar with the structure and requirements and all the shortcodes supported by both Hugo and the theme.

We override some of the Dot themes styling and functionality in the layouts and static folders within the Documentation repository.

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
repository: https://github.com/dolittle/Documentation
weight: 2
---

Enable “Edit on Github” for your repository

Enable support for “Edit on Github” pencil icon on a page by adding a reference to the repository on the _index.md Front Matter:

An example of front-matter with repository set:

---
title: About contributing to documentation
description: Learn about how to contribute to documentation
keywords: Contributing
author: dolittle
repository: https://github.com/dolittle/Documentation
---
Do not include a trailing slash at the end of the repository URL.

All sub-articles will use this repository as the base for the links generated to edit files on GitHub.

_index.md files

The _index.md files within subfolders should only contain the Front Matter and nothing else. This makes the subfolder links on the sidebar work as only dropdowns without linking to the content of the _index.md. We prefer this as it makes for a more smooth experience on the site.

You should only have an _index.md file for the uppermost landing page of dolittle.io like Getting started, Contributing etc.

These 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.

Within same repository

When adding links to other pages inside the same repository DO NOT USE the file extension .md - otherwise the link will be broken. For instance, linking to the API documentation is done by adding a markdown link as follows:

[API](./api)

Renders to:

API

Cross Repositories

Link pages from other repositories using Hugos relref/ref functions inside the markdown.

The root of the documentation for references is Source/content/ folder of Documentation repository:

Here is a [link]({{< ref "/getting-started/tutorial/setup.md" >}}) to the Quickstart page.

Renders to:

Here is a [link]() to the Quickstart page.

You can also let Hugo figure out the correct path:

Some text [with a link]({{< ref style_guide >}})

Renders to:

Some text [with a link](/contributing/documentation/documentation/style_guide/)

Be aware that this matches the filename with or without the .md suffix. If there are other documents with the same name, you’ll need to either rename those or include the entire path to the file.

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. Examples of Mermaid

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.

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:

alt-text

The URL to the image needs to be fully qualified, typically pointing to the GitHub URL. This is something being worked on and registered as an issue here.
The path is relative to the document where you declare the link from.

Notices

Hugo supports different levels of notices:

Tip

Use tips for practical, non-essential information.

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

Renders to:

You can also create ReadModels with the CLI tool.

Note

Use notes for important information.

{{% notice note %}}
You can only run one `dolittle-documentation-server` command at a time.
{{% /notice %}}

Renders to:

You can only run one dolittle-documentation-server command at a time.

Warning

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

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

Renders to:

Do not remove artifacts.json if you do not know what you’re doing.