Skip to content

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.

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#