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.