MkDocs
An onbuild image for building MkDocs sites. A Dockerfile that starts FROM this image runs its ONBUILD instructions, which copy in the project's mkdocs.yaml and docs/, then run mkdocs build --strict to write the static site to /app/site.
registry.gitlab.com/hosstio/docker-images/mkdocs/main:latestSource: hosstio/docker-images/mkdocs
The image is based on python:3-slim and installs the latest MkDocs at build time, since its requirements.txt pins no versions.
Usage
Config file
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
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
- mermaid2Themes
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 |