sommerfeldio/mkdocs repository overview

⁠sommerfeldio/mkdocs

This image is used to build the documentation using the mkdocs toolchain and is based on Material for MkDocs⁠.

• sommerfeldio/mkdocs⁠ on Docker Hub
• Dockerfile source code⁠ on GitHub
• How to Contribute⁠
• Visit the projects documentation page⁠ for a list of all available container images.

⁠DEPRECATION NOTICE: sommerfeldio/mkdocs is deprecated as of version 0.28.1

Starting with 0.28.1, the sommerfeldio/mkdocs container image will no longer be maintained. This means:

• No new features
• No bug fixes
• No security updates
• No dependency upgrades

The image will remain available on GitHub, but it is stale and should not be relied upon for anything going forward. 0.28.1 is the last version available on Docker Hub.

sommerfeldio/mkdocs is built on Material for MkDocs⁠, which in turn depends on MkDocs. MkDocs has been unmaintained since August 2024, with no releases in over a year. As a result, Material for MkDocs itself has entered maintenance mode, and the team has announced Zensical⁠ as its successor - a next-generation static site generator that consolidates static site generation, theming, and customization into a single coherent stack, free of the MkDocs dependency.

⁠Recommended migration: sommerfeldio/zensical

Switch to sommerfeldio/zensical as a drop-in replacement. Because Zensical guarantees compatibility with Material for MkDocs, migrating away from sommerfeldio/mkdocs should require little to no change to your documentation sources.

• Reads your existing mkdocs.yml natively, so you can build your current project with minimal changes.
• Leaves your Markdown files, template overrides, and CSS/JavaScript extensions untouched (the generated HTML is unchanged and content is still processed via Python Markdown).
• Ships as fully Open Source (MIT-licensed).

Review the Zensical compatibility page⁠ before migrating if you rely on specific plugins.

⁠Learn more

• Zensical announcement: https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/⁠
• Zensical website: https://zensical.org/⁠
• Zensical compatibility: https://zensical.org/compatibility/⁠

⁠About the latest stable release which is sommerfeldio/mkdocs:0.28.1

This image extends the squidfunk/mkdocs-material⁠ image with the mkdocs-kroki-plugin⁠ to allow rendering diagrams and charts using Kroki.io⁠. A dedicated Dockerfile is needed because the base image does not provide all necessary plugins and tools.

The image focuses on generating the documentation site (e.g. from a pipeline). It is not intended to be used as a live webserver for production.

⁠Software Tags and Versioning

Learn about our tagging policy and the difference between rolling tags and immutable tags on our documentation page⁠⁠.

⁠Software Bill of Materials (SBOM)

Starting with version 0.25.2, a Software Bill of Materials (SBOM) in SPDX format is generated for every image at build time and attached directly to the image in Docker Hub as an OCI attestation, available for the edge, latest and versioned tags. Retrieve it with

• docker scout sbom sommerfeldio/mkdocs:latest or
• docker buildx imagetools inspect sommerfeldio/mkdocs:latest --format "{{ json .SBOM }}".

The same SBOM is also attached as a downloadable asset on each GitHub release⁠.

⁠Usage

This image supports two modes. The build command is used to build the documentation site based on your Markdown docs. The container terminates after the build is complete. Additionally the image offers a development server to preview the documentation site. Both features originate in the squidfunk/mkdocs-material⁠ base image.

The easiest way to use the image is to run it with Docker Compose:

services:

  docs-build:
    container_name: docs-build
    image: &docs-image sommerfeldio/mkdocs:latest
    volumes: &volumes
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
      - .:/workspaces/your-project
    working_dir: &default-workdir /workspaces/your-project
    command: build

  docs-dev-server:
    container_name: docs-dev-server
    image: *docs-image
    volumes: *volumes
    working_dir: *default-workdir
    ports:
      - 3080:8000

The development server is not recommended for production use. It is intended to be used during the development of the documentation site. For production use, the build command should be used to generate the static site. This triggers the production-level compilation and minification of all style sheets and JavaScript files. The resulting static site can be served by a web server like nginx⁠ or Apache httpd⁠.

For information on how to get started with Material for MkDocs⁠, please refer to the official "Getting started" guide of the projects documentation⁠.

For information on how to configure the mkdocs-kroki-plugin, please refer to the official documentation of the plugin⁠.

⁠License

This container image is inheriting the MIT License from the GitHub repository⁠.

The license from this GitHub repository is compatible with the license from the squidfunk/mkdocs-material project⁠ (which is MIT as well).