thenetworkfactory/mkdocs-material repository overview

⁠mkdocs-material

MkDocs with the Material theme and a batteries-included plugin set, pinned and dependency-checked at build time.

Ships MkDocs + Material with macros, kroki, mermaid2, print-site, include-dir-to-nav and markdownextradata, plus the WeasyPrint stack for the optional PDF-export plugins.

⁠Get it

docker pull thenetworkfactory/mkdocs-material

⁠What it is for

Building and serving a MkDocs site in CI or locally, without installing the Python toolchain on the host. Point it at a docs repository and it renders or serves it.

⁠Layout it expects

The docs repo is bind-mounted at /root, the image's working directory. The config path is relative to that mount, which matters when the config does not sit at the repo root — for example at docs/config/mkdocs.yml:

docker run --rm -v "$PWD:/root" -p 8000:8000 \
    thenetworkfactory/mkdocs-material \
    mkdocs serve --dev-addr=0.0.0.0:8000 \
                 --config-file docs/config/mkdocs.yml

Why the working directory is the repo root and not the config's own directory: the macros plugin resolves include_dir relative to the process CWD. A project setting include_dir: docs/config/_includes needs the CWD to be the repo root for that path to resolve.

Why /root and not a tidier /docs: it is what existing users of this image mount, and the macros plugin resolves include_dir from the CWD — so changing it breaks those builds with MACROS ERROR: Include directory ... does not exist!. If you mount somewhere else, set the working directory to match.

⁠Dependencies

Pinned in requirements.txt, direct dependencies only; pip resolves the rest. Verified with pip check at build time — the build fails if the set ever conflicts.

Base image is python:3.14-slim, chosen over 3.12 because it carries roughly half the HIGH-severity CVEs (41 vs 80) while still running the whole plugin set, the two unmaintained PDF plugins included. The Dockerfile also runs apt-get upgrade to pick up Debian security updates published after the base image was cut. The CRITICALs that remain are base-image perl / glib issues with no upstream fix.

The libpango / libharfbuzz / libpangoft2 apt packages are the WeasyPrint rendering stack. They are needed only by the optional pdf-export / with-pdf plugins, which are commented out of most mkdocs.yml files — but they must be present at image build time or enabling either plugin fails at runtime.

⁠Known upstream deprecation

mkdocs-material-extensions is on its final release. Configs still using:

emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg

should move to the in-theme path, which this image also provides:

emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg

Both work in this image today; the old path logs a deprecation warning.

⁠Kroki

The kroki plugin renders diagrams by POSTing to a kroki server — https://kroki.io by default, overridable with KROKI_SERVER_URL. Its fail_fast option defaults to false, so an outage degrades the diagrams rather than failing the build.

Note kroki >=1.x renamed its options to snake_case. The old HttpMethod / DownloadImages / EmbedImages spellings are silently ignored with an "Unrecognised configuration name" warning — a config using them is not getting the behaviour it looks like it asks for.

Maintained by AxisOps.