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
devversion of docs website
Working locally
Checkout the branch that contains the documentation:
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:
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:
- use the manual approach
- Create a custom docker image with the plugin installed:
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:
pip install -r requirements.txt
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.
Created: 2021-11-10