svcops/mkdocs-builder repository overview

⁠MkDocs Builder

MkDocs Builder is a Docker image for building MkDocs documentation sites. It is based on python:3.11-slim and includes MkDocs, the Material theme, and commonly used MkDocs plugins. It is suitable for local builds, CI/CD pipelines, and temporary documentation build environments.

⁠Quick Start

Run the following command in a project directory that contains mkdocs.yml:

docker run --rm \
  -v "$PWD":/docs \
  -w /docs \
  mkdocs-builder:latest \
  mkdocs build --clean

After the build completes, the generated static site will be written to the site/ directory in the current project.

For Windows PowerShell:

docker run --rm `
  -v "${PWD}:/docs" `
  -w /docs `
  mkdocs-builder:latest `
  mkdocs build --clean

⁠Local Preview

To preview the documentation site locally, start the MkDocs development server:

docker run --rm -it \
  -p 8000:8000 \
  -v "$PWD":/docs \
  -w /docs \
  mkdocs-builder:latest \
  mkdocs serve --dev-addr=0.0.0.0:8000

Then open:

http://localhost:8000

⁠Included Packages

This image includes the following Python packages:

• mkdocs
• watchdog
• livereload
• pygments
• mkdocs-material
• pymdown-extensions
• mkdocs-awesome-pages-plugin
• mkdocs-git-revision-date-localized-plugin
• mkdocs-minify-plugin

⁠Common Commands

Show the MkDocs version:

docker run --rm mkdocs-builder:latest mkdocs --version

Create a new MkDocs project:

docker run --rm -it \
  -v "$PWD":/workspace \
  -w /workspace \
  mkdocs-builder:latest \
  mkdocs new my-docs

Build documentation from a specific directory:

docker run --rm \
  -v "$PWD/my-docs":/docs \
  -w /docs \
  mkdocs-builder:latest \
  mkdocs build --clean

⁠Build the Image Locally

To build the image from source:

docker build -t mkdocs-builder:latest .

The default build argument is:

BUILD_ORIGIN=LOCAL

When BUILD_ORIGIN=LOCAL, the build process uses the Tsinghua PyPI mirror to install Python dependencies. To use the default PyPI source instead, set:

docker build --build-arg BUILD_ORIGIN=GITHUB_ACTIONS -t mkdocs-builder:latest .

⁠CI/CD Example

In CI/CD pipelines, mount the repository to /docs and run the build command directly:

docker run --rm \
  -v "$PWD":/docs \
  -w /docs \
  mkdocs-builder:latest \
  mkdocs build --clean --strict

The --strict option makes the build fail when configuration issues or broken links are detected, which is useful for pipeline validation.

⁠Directory Layout

The image does not enforce a specific project structure. It only requires a valid mkdocs.yml in the working directory. A common layout looks like this:

.
|-- mkdocs.yml
|-- docs
|   |-- index.md
|   |-- api.md
|   `-- guide
|       `-- install.md
`-- site

The site/ directory is generated by mkdocs build.

⁠Notes

• This image is intended for building and previewing MkDocs documentation. It does not include a production web server.
• The recommended working directory is /docs; mount your documentation project to this path.
• If your documentation requires additional Python packages, create a derived image based on this image and install the extra dependencies there.