The purpose of this repostitory is to provide a markdown based template for setting up git hosted software architecture documentations ("documentation as code")

For layout, the mkdocs-material plugin is used.

For architecture documentation, a single page template from arc42 is used. The content of the pre defined template in index.md has to be adjusted based on the personal preferences.

More information and examples about the arc42 template can be found on the official homepage.

To use this template, you need a python3 installation and setting up a virtual environment:

virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements.txt

To review and check formats, you can start the mkdocs engine using following command:

mkdocs serve

More information about the material plugin can be found here.

More information about the mkdocs engine can be found here.

It is possible to specify mermaid diagrams and also include them in the preview window of vscode using the mermaid extension

On mkdocs side, the mermaid plugin is already added by default.

It is possible to include png pictures and edit them in vscode using .drawio.png file formats and the draw.io extension

If you want to deploy your mkdocs on github pages in order to provide access to everyone, you can simply do this following the official documentation