hedgedoc/docs/content/how-to/develop/documentation.md
Philip Molares e07cd62596 docs: restructure documentation
This rewrite follows the principles of https://diataxis.fr/

Co-authored-by: Erik Michelson <github@erik.michelson.eu>
Signed-off-by: Philip Molares <philip.molares@udo.edu>
Signed-off-by: Erik Michelson <github@erik.michelson.eu>
2023-09-17 21:50:21 +02:00

1.9 KiB

Documentation

Our documentation is build with mkdocs. While you can write documentation with every text editor you like, if you want to build the documentation and want to see at how it will look you need to have python3 and mkdocs installed.

Writing

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

The configuration for mkdocs lies in the docs folder in a file called mkdocs.yml. With that file the theme and menu - among others - can be configured. Please note: Any new files need to be linked to by other files or put in the navigation, otherwise 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. python3 --version
  2. Go into the docs folder.
  3. Install all the dependencies (E.g. with a venv) with pip install -r requirements.txt
  4. Start the mkdocs dev server (mkdocs serve) or build the documentation (mkdocs build).

If you run mkdcs serve a local server will serve the mkdocs files and change the served files as you write documentation.

Deployment

The documentation is deployed with mkdocs.

The repository docs.hedgedoc.org is used to deploy the actual website to github.io. Currently only the master branch is deployed as it contains the latest release.