About

This repository contains source code for the Zarhus documentation webpage.

Contribution

Please make sure to follow below steps before publishing your changes as a merge request.

Local build

python3 -m venv scripts/venv
source venv/bin/activate
pip install -r requirements.txt
mkdocs serve

By default, it will host a local copy of documentation at: http://0.0.0.0:8000/.

If the following error occurs OSError: [Errno 98] Address already in use, try using a different address by running the command mkdocs serve -a localhost:12345 (the number is random).

It is crucial at this point to verify that the pages you have changed render correctly as HTML in local preview.

Make sure no TBD or TODO content is displayed

Find all occurrences:

grep -E "TBD|TODO" docs/**/*.md -r

Iterate over all occurrences and check if:

• file, where TBD or TODO occurs, is displayed (included in nav section of mkdocs.yml)
• TBD or TODO is visible on the website

There should be no TBD or TODO visible on the website.

pre-commit hooks

• Install pre-commit, if you followed local build procedure pre-commit should be installed

• Install hooks into repo:

  pre-commit install

• Enjoy automatic checks on each git commit action!

• (Optional) Run hooks on all files (for example, when adding new hooks or configuring existing ones):

  pre-commit run --all-files

To skip verification

In some cases, it may be needed to skip pre-commit tests. To do that, please use:

git commit --no-verify

Embedding videos

Embedding videos with in-line HTML iframe tag does not work. mkdocs-video plugin is used instead. To embed an video simply type the following in markdown: ![type:video](https://www.youtube.com/embed/LXb3EKWsInQ) (example).

Embedding subscribe forms

It is possible to embed subscribe form for the selfhosted Listmonk mailing lists. To do that, paste the custom macro content in the target markdown file:

{{ subscribe_form("FORM-ID",
"Button text") }}

where:

• FORM-ID - target mailing list form ID that can be found here.
• Button text - text to be shown on the button.