The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
All Dolittle documentation is generated using Hugo.
It basically works with GitHub flavored markdown and turns this into HTML pages that we then host.
The documentation sits separated into the repository it belongs to and is expected to be in a folder called
inside at the root of the repository. Documentation is updated whenever a pull request
is approved. This will then automatically trigger Hugo to build and re-render the pages.
This documentation documenting the documentation process is also adhering to this and as an example you can find it here.
The documentation is using a fork of a theme called DocDock. 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.
All files MUST have a metadata header at the top of the file following the following format:
--- title: About contributing to documentation description: Learn about how to contribute to documentation keywords: Contributing ---
Some of this metadata gets put into the generated HTML file and some of it is used for indexing and other purposes and for future expansion.
All files MUST be lower cased, words MUST be separated with underscore. Example:
When adding links to other pages you MUST NOT include the file extension
.md - otherwise the link
will be broken. For instance, linking to the API documentation is done by adding a markdown link
Even though the file is actually called
Linking to external resources, is done in the standard Markdown way:
In order to cross-reference content that sits in a different repository…..
More details coming soon
Diagrams / Figures
All diagrams and figures SHOULD be done using the Mermaid shortcode. Mermaid has more features and is well documented here.
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.
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
<repository root> └── Documentation └── MyArea └── [markdown files] └── images [image files]
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.
Read more here
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.
All documentation is written in markdown following the GitHub flavor. Markdown can be written using the simplest of editors (Pico, Nano, Notepad), but there are editors out there that gives great value and guides you through giving you feedback on errors. Editors like Visual Studio Code and Sublime Text comes highly recommended. VSCode has for instance a markdown preview feature.