Get started

All of Dolittles documentation is open-source and hosted on GitHub.

Add a new repository to the main Documentation repository

This guide teaches you how to add a new repository to the Dolittle documentation structure.

Start by cloning the Documentation repository and its submodules:

$ 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

1. Create documentation for the new repository

At the root of the working repository, create a Documentation folder with at least a matching _index.md and other markdown files if needed. Read our guide on structure for more information.

2. Adding the working repository as a submodule

In the Documentation repository, navigate to the Source/repositories/ folder and pull your working repository here as a submodule:

$ git submodule add <repository_url> <repository_name>

3. Linking submodules to content

The system relies on all documentation content sitting in the Source/content folder. This includes markdown files, images and other resources you link to your documentation.

The content folder contains the parent folders, with a matching _index.md and the contents of the Documentation folder from the repository directly in this.

This is done by creating a symbolic link to the repositories Documentation folder.

<Documentation root>
└── Source
    └── content
        └── fundamentals
        └── runtimes
        └── ...

Open a shell and navigate to the correct sub-folder in the content folder and then in the corresponding organisation folder.

Unix:

$ ln -s ../../repositories/<organisation-folder>/<repository>/Documentation <folder-name>

Windows:

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

Example:

Unix:

$ ln -s ../../repositories/runtime/Runtime/Documentation runtime

Windows:

c:> mklink /d runtime c:\Projects\Dolittle\Documentation\Source\repositories\runtime\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.

Writing

All documentation is written in markdown following the GitHub flavor.

Markdown can be written using simple text editors (Pico, Nano, Notepad), but more thorough editors like Visual Studio Code or Sublime Text are highly recommended. VSCode also has a markdown preview feature.

Read the writing guiden and style guide for more information.