One best practice we follow regarding documentation is to keep it close to what it describes, we prefer including those files together with the actual code, in a different docs/ folder. We write them in Markdown because it is a simple and easy to understand format that is automatically rendered correctly when browsing those files in Gitlab.

And because we are Gitlab users, we are also able to use other features like Gitlab pages and the mermaid support in markdown to generate even better and useful documentation.

Using mkdocs for generating public documentation

There is Gitlab repository that demonstrates this process, important bits about this specific repository are:

• .gitlab-ci.yml configuration explicitly using the forked image and copying the CSS fixes before the build, and
• mkdocs-mermaid forked plugin that includes specific fixes for the bundle readthedocs theme and docker support.

The final result:

• mkdoc documentation using readthedocs and, the equivalent
• Gitlab markdown rendered

Back to posts