hedgedoc/docs/dev/documentation.md

Documentation

Our documentation is build with mkdocs.

Writing

All documentation files are found in the docs directory of the hedgedoc/hedgedoc repo. These files are just normal markdown files with nothing special about them.

The config file for mkdocs lies in the root of the repo in a file called mkdocs.yml. With that file the theme and menu - amoung others - can be configured. Please note: Any new files need to be linked to by other files or put in the navigation or the files will be very hard to find on the documentation website.

Building

To build the documentation locally you need to perform the following steps:

1. make sure you have python3 installed
2. install all the dependencies possibly with a venv:
   pip install -r mkdocs.requirements.txt
3. start the mkdocs dev server mkdocs serve or let it build the documentation mkdocs build

Deployment

The documentation is deployed with Messor Structor.

The necessary Dockerfile and version menu template and also the github action to build the whole documentation can be found in the docs.hedgedoc.org repo. This repo is also used to deploy the actuall website to github.io.

Messor Structor builds and deploys the documentation by finding all branches that follow the pattern v* and build each one seperatly via mkdocs by first installing mkdocs.requirements.txt and then building. Afterwards the menu go template is used to include a version switcher in the theme and make all the different versions available.