Setting up MkDocs for publishing project code documentation

Introducing MkDocs

Among the tools in my Markdown toolkit, MkDocs is one of my favorites. I primarily use it for its intended purpose: publishing Markdown-based documentation for project code. On occasion, MkDocs is my preferred tool for publishing non-documentation related content when that content consists of large swathes of difficult-to-navigate information. The extensibility of MkDocs combined with its healthy plugin ecosystem provides more ways to customize the content publishing experience than alternatives like Gollum.

Prerequisites

Basic knowledge of Docker and Docker Compose
Familiarity with Markdown syntax
A project requiring documentation

Getting started

We'll use one of the excellent containers released by minidocks:

minidocks/mkdocs (Docker Hub)
minidocks/mkdocs (Source code on GitHub)

We can run MkDocs with its own docker-compose.yaml file:

services:
  mkdocs:
    image: minidocks/mkdocs
    restart: always
    ports:
      - '8000:8000'
    volumes:
      - ${PWD}:/app
    working_dir: /app

Note

The above configuration mounts your current directory into the container and exposes MkDocs on port 8000.

Alternatively, we can combine it with Gollum if we want both services to publish content in the current directory:

services:
  gollum:
    image: gollumwiki/gollum:master
    restart: always
    ports:
      - '4567:4567/tcp'
    volumes:
      - ./config.rb:/etc/gollum/config.rb
      - ./wikidata:/wiki
    command:
      - '--config=/etc/gollum/config.rb'
  mkdocs:
    image: minidocks/mkdocs
    restart: always
    ports:
      - '8000:8000'
    volumes:
      - ${PWD}:/app
    working_dir: /app

Extending MkDocs with plugins

While the minidocks/mkdocs image comes with numerous pre-installed plugins, you may need to add plugins that aren't included by default. Let's walk through the process of extending the base image to include additional functionality.

Building a custom Docker image

Suppose we want to use the mkdocs-file-filter-plugin that isn't installed in the base image. We can create a new image that builds upon minidocks/mkdocs with just a few steps.

First, let's create a working directory for our new image:

mkdir -p ~/code/docker/mkdocs/minidocks-addon
cd ~/code/docker/mkdocs/minidocks-addon
touch Dockerfile

In this directory, we'll create a Dockerfile that instructs pip to install our desired plugin:

FROM minidocks/mkdocs
RUN pip install \
        mkdocs-file-filter-plugin

Tip

Keep your Dockerfile simple and focused on just the plugins you need. This helps maintain a smaller image size and reduces potential conflicts.

Adding GitHub-based plugins

If you need to install plugins directly from GitHub, such as mkdocs-pagenav-generator, you'll need to ensure git is available in the container:

FROM minidocks/mkdocs
RUN apk add git && pip install \
        mkdocs-file-filter-plugin \
        "git+https://github.com/Andre601/mkdocs-pagenav-generator.git"

Caution

Installing `git` will increase the size of the otherwise slim image. Only add it if you absolutely need GitHub-hosted plugins.

Building the custom image

Now we're ready to build our custom image, which we'll call mkdocs-addon:

# Create image from directory with Dockerfile
docker build -t mkdocs-addon .

Updating the docker-compose.yaml file

Next, update your docker-compose.yaml file to use the newly created mkdocs-addon image:

services:
  gollum:
    image: gollumwiki/gollum:master
    restart: always
    ports:
      - '4567:4567/tcp'
    volumes:
      - ./config.rb:/etc/gollum/config.rb
      - ./wikidata:/wiki
    command:
      - '--config=/etc/gollum/config.rb'
  mkdocs:
    image: mkdocs-addon
    restart: always
    ports:
      - '8000:8000'
    volumes:
      - ${PWD}:/app
    working_dir: /app

Configuring MkDocs to use the plugins

Finally, update the plugins section of your mkdocs.yml configuration file to load the newly installed plugins:

plugins:
  - search
  - file-filter
  - pagenav-generator

Important

Always verify that your plugins are compatible with your version of MkDocs to avoid potential issues during document generation.

Conclusion

With these steps, you now have a customized MkDocs setup running in Docker that includes additional plugins to enhance your documentation workflow. This approach maintains the benefits of containerization while allowing you to extend functionality as needed for your specific project requirements.

For further exploration of MkDocs capabilities and available plugins, consider the following resources: