Skip to content

Documentation

This website is built using mkdocs from the contents of the main (default) branch.

The mkdocs.yml file in the repository root configures the build process, including the available plugins.

Editing

All content lives under the docs/ directory in the repository.

To add new sections/articles, create new directories and files under the docs/ directory, in Markdown format.

The pencil icon is a shortcut to quickly edit the content of the page you are viewing on the website:

Screenshot showing edit pencil

Above: Screenshot showing the edit pencil circled in red

Features

  • Mermaid

    Use code fences with mermaid type to render Mermaid diagrams within docs. For example, this markdown:

    ```mermaid
    graph LR
        Start --> Stop
    ```
    

    Yields this diagram:

    graph LR
        Start --> Stop

Running locally

The documentation website can be run locally using Docker Compose:

# from inside the .devcontainer/ directory
docker compose up docs

The site is served from http://localhost at a port dynamically assigned by Docker. See Docker dynamic ports for more information.

The website is automatically rebuilt as changes are made to docs/ files.

In the Devcontainer

When running the Devcontainer, the docs site is automatically started.

See Docker dynamic ports for more information on accessing the site on localhost.

Deploying

A GitHub Action watches for pushes to main, and uses mhausenblas/mkdocs-deploy-gh-pages to build the mkdocs content, force-pushing to the gh-pages branch. At that point, GitHub Pages redeploys the docs site.