Contributing to the Docs

Our documentation is written as Markdown files and served via GitHub Pages by MkDocs.

Writing the docs

As our documentation is written in Markdown, the base Markdown specification is a useful reference. MkDocs also includes some documentation to get you started writing in Markdown.

In addition to standard Markdown, our documentation supports the following extensions:

  • Admonitions adds specially called-out text anywhere within the document as notes, warnings, and other types.

  • BetterEm improves the handling of bold and italics.

  • MagicLink provides automatic linking for URLs in the Markdown text.

  • SuperFences makes a number of improvements to standard Markdown code fences.

  • Tilde adds support for creating <del></del> tags with ~~.

  • Tables adds support for tables to standard Markdown.

When creating new documents, they should be added to the mkdocs.yml file in the appropriate place under nav: to get them to appear in the sidebar navigation. For example:

- Introduction:

Running the docs locally

With Docker

When running using Docker-compose, this documentation is running by default at http://localhost:8888.


When using the stand-alone installation of, you can run these docs with:

pip install -r requirements/docs.txt
mkdocs serve -a :8888

Once running, they are accessible at http://localhost:8888.

Deploying the docs to GitHub Pages

Every time a PR is merged to main, GitHub Actions will build and deploy the documentation to See How we use GitHub Actions for more info.

If you would like to deploy to a fork of owned by another user you can provide the -r argument:

mkdocs gh-deploy -r USER

Where USER is the GitHub user. The docs will then be available at after a short period of time.

See the the MkDocs documentation for more information.