Skip to content

Working with the documentation

This documentation site is built using MkDocs and mkdocs-material. These tools generate a static website based on a configuration file and a set of markdown files in the docs/main branch.

docs/main is a detached branch that is locked and only accepts PRs. Two Actions are triggered by the PR:

  • On PR creation: Markdown linting and link checking
  • On PR merge: deployment of dev version of docs website

Working locally

Checkout the branch that contains the documentation:

git worktree
git checkout docs/main

# If you want to have `dev` branch and `docs` branch side by side,
# try out git worktree

# from the working folder:
git worktree add c:/path-to-sources/lorawan.docs docs/main

The recommended approach is using docker to serve the static site locally:

serve documentation locally
docker pull squidfunk/mkdocs-material

# in the folder where the `docs/main` branch lives locally:
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

Now you can see the site running locally on http://localhost:8000. You can change the port in the docker run command.

Required extensions

We are using extensions which are not supported by the mkdocs-material container out-of-the-box. There are two ways to deal with this:

  1. use the manual approach
  2. Create a custom docker image with the plugin installed:
Dockerfile
FROM squidfunk/mkdocs-material
COPY requirements.txt .
RUN pip install -r requirements.txt

The Dockerfile is available in the repo as well.

```bash title="Build and run container"
# in the directory where your dockerfile is
docker build . -t mkdocs-material-with-extensions
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs mkdocs-material-with-extensions
```

Alternate approach

Install Python and pip, and then the required packages:

install prerequisites
pip install -r requirements.txt
run mkdocs
mkdocs serve

Deployment

For deployment, the additional toolset mike is used. This tool allows us to deploy multiple versions of the documentation. There is a manual GitHub Action to deploy a specific version.

Configuration

The file mkdocs.yml provides the main configuration for the website, such as color and themes, plugins and extension. The TOC is also defined in the config file, under the section nav.

TOC is not auto-generated

Currently, new pages are not automatically added to the TOC. You will need to manually add new pages to the nav section of the configuration file.

Last update: 2022-01-07
Created: 2021-11-10
Back to top