Getting started

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.

Writing documentation can be done by just working on each repository individually or you can work with the documentation
engine and see the end result while working. This is a good idea to get a feeling for how it will look like and verify
that links, images and diagrams are correct.

You’ll have to start by cloning the Documentation repository, which has sub modules:

$ git clone --recursive https://github.com/dolittle/documentation

If you’ve already cloned it, you can get the submodules by doing the following:

$ git submodule update --init --recursive

The system is relying on all content sitting in the content folder:

<repository root>
└── Source
└── Hugo
└── content

Its expecting a folder for each top-level repository and the content of the Documentation folder directly in this.
This is best achieved by creating a symbolic link to the repositories Documentation folder.

Open a shell and navigate to the content folder.

Unix:

$ ln -s <repository-folder>/Documentation <folder-name>

Windows:

c:> mklink /d <folder-name> <repository-folder>\Documentation

Example:

Unix:

$ ln -s /Projects/Dolittle/Runtime/Documentation Overview

Windows:

c:> mklink /d Overview c:\Projects\Dolittle\Runtime\Documentation

Chances are you are contributing to the code of the repository and you can therefor leave it in place and maintain
code and documentation side-by-side.

Building and running

Install dependencies

You need to install node dependencies in the Source/Hugo folder. You can do this through using npm or yarn.

NPM:

$ npm install

Yarn:

$ yarn

Install Hugo

You will need to install Hugo.
Once you have Hugo installed, you open a shell and navigate to the Source/Hugo folder.
From this you simply do:

It is now a matter of opening up a browser to the URL http://localhost:1313 and start writing documentation.
With the default option, the page will live reload when saving any files.

Writing

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.