MkDocs

An onbuild image for building MkDocs sites. A Dockerfile that starts FROM this image copies in the project's mkdocs.yaml and docs/, then runs mkdocs build --strict, which leaves the static site in /app/site.

registry.gitlab.com/hosstio/docker-images/mkdocs/main:latest

Source: hosstio/docker-images/mkdocs

The image runs on python:3-slim and installs the latest MkDocs at build time, since its requirements.txt pins no versions.

Usage

Name the config file mkdocs.yaml. The image doesn't copy MkDocs' default mkdocs.yml, so a project that keeps that name fails the build.

Build the site in one stage and serve /app/site from another, for example with nginx:

FROM registry.gitlab.com/hosstio/docker-images/mkdocs/main:latest AS docs

FROM nginx:alpine
COPY --from=docs /app/site /usr/share/nginx/html

--strict turns MkDocs warnings, such as a link to a missing page, into build failures.

Plugins

The image installs mkdocs-mermaid2 for Mermaid diagrams. Enable it in mkdocs.yaml, and list search too, because a plugins key replaces MkDocs' default plugin list:

plugins:
  - search
  - mermaid2

Themes

MkDocs ships the mkdocs and readthedocs themes, and the image adds Material. Pick one under theme in mkdocs.yaml:

Theme	theme.name	Demo
MkDocs (default)	mkdocs	Live demo
Read the Docs	readthedocs	Live demo
Material	material	Live demo