Documentation ¶

This website is built using mkdocs from the contents of the dev (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 ¶

Material for MkDocs: Reference

See mkdocs.yml for enabled plugins/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 dev, 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.