Contributing

Please help us expand this knowledge base by contributing!

Tools

This site used the following tools:

• Markdown documents
• MkDocs for converting markdown documents to HTML
• Material for MkDocs theme
• Python 3 (required by MkDocs)

Markdown

From Writing with Markdown:

MkDocs pages must be authored in Markdown, a lightweight markup language which results in easy-to-read, easy-to-write plain text documents that can be converted to valid HTML documents in a predictable manner.

MkDocs uses the Python-Markdown library to render Markdown documents to HTML. Python-Markdown is almost completely compliant with the reference implementation, although there are a few very minor differences.

In addition to the base Markdown syntax which is common across all Markdown implementations, MkDocs includes support for extending the Markdown syntax with Python-Markdown extensions. See the MkDocs' markdown_extensions configuration setting for details on how to enable extensions.

Directory Layout

• mkdocs.yml: Configuration file
• docs/: Source documents (Markdown)
• site/: HTML Output (doesn't need to be in git repo, but is included for quick viewing)
• .venv/: Python virtual environment (created by make install; not in git repo)

Using MkDocs

To use MkDocs, you need Python 3.

We also make use of GNU Make to simplify the commands we need to run. See Makefile for details on the steps that are performed for each target if you're curious, or would prefer to run them manually.

Install mkdocs (in a local Python virtual environment) with:

Bash

make install

Run in development mode while writing:

Bash

make serve

Build the site:

Bash

make build

You can also build a container image & run it, with:

Bash

make container-run
make container-stop

Adding Documents

To add a page to the site, simply create a new Markdown (.md) file to the docs/ directory.

Any files which are not identified as Markdown files (by their file extension) within the documentation directory are copied by MkDocs to the built site unaltered. See this documentation to link to images in your pages.

To add it to the left hand navigation pane, add the path to your file to the nav section of the mkdocs.yml configuration file.

For more details & documentation, start at the Getting Started with MkDocs guide.

Finally, just run make serve and visit the provided link (http://127.0.0.1:8000/) to preview your site.

Once you're happy, run make build, commit the changes to the git repo, and push it GitHub.