MkDocs Documentation Development#

This document describes how we develop MkDocs documentation.

Prerequisites#

1. Install Visual Studio Code

Repositories#

We host our documentation using the ES S4 service.

• Onboarding docs
• User docs

Develop#

1. Clone the needed repositories.
2. Open the repository directory in Visual Studio Code.
3. Create a python virtual environment in the repository directory (one time setup).

   python3 -m venv venv
   source venv/bin/activate
   python3 -m pip install mkdocs
   python3 -m pip install mkdocs-material-extensions
   python3 -m pip install mkdocs-material
   python3 -m pip install mkdocs-mermaid2-plugin
   python3 -m pip install mkdocs-macros-plugin
   python3 -m pip install pymdown-extensions
   

4. Activate the environment and start a local mkdocs server (every time setup).

   source venv/bin/activate
   python3 -m mkdocs serve
   

5. Open http://127.0.0.1:8000/development-environment/mkdocs/ in your browser.
6. Your browser should automatically refresh every time you save a file.
7. Press ctrl+c to break out of the mkdocs serve command when done developing to stop the server.

Deploy#

Create a merge request in the repository. Once reviewed and merged, it will automatically be pushed to production.

Resources#

• MkDocs Site
• Writing your docs
• Markdown basics and Syntax
• Python-Markdown extensions