Skip to content

Setting Up MkDocs with Docker Compose

Introduction to MkDocs

MkDocs is a static site generator that's geared towards project documentation. With the Material theme, it provides a sleek, responsive, and user-friendly interface for your documentation projects.

Docker Compose Configuration for MkDocs

This Docker Compose setup deploys MkDocs with the Material theme in a Docker container, allowing you to easily manage and preview your project documentation.

Docker Compose File (docker-compose.yml)

version: '3'
services:
  mkdocs:
    image: squidfunk/mkdocs-material
    ports:
      - "8005:8000"
    volumes:
      - ./:/docs
    stdin_open: true
    tty: true

Key Components of the Configuration

Service: MkDocs

  • Image: squidfunk/mkdocs-material is the Docker image used for MkDocs with the Material theme.
  • Ports:
  • 8005:8000 maps port 8005 on the host to port 8000 in the container, where MkDocs's web interface is accessible.
  • Volumes:
  • ./:/docs: Maps the current directory (project documentation) to the /docs directory in the container.
  • Interactive Mode: stdin_open: true and tty: true allow interactive processes, which is useful for live reloading during documentation development.

Deploying MkDocs

To deploy MkDocs with Docker Compose, follow these steps:

  1. Create a New Directory:
  2. Create a new directory on your host system for your MkDocs container. You can name it mkdocs or any other name of your choice.

  3. Docker Compose File:

  4. Inside this new directory, create a docker-compose.yml file.
  5. Save the following Docker Compose configuration into this file:

    version: '3'
    services:
      mkdocs:
        image: squidfunk/mkdocs-material
        ports:
          - "8005:8000"
        volumes:
          - ./:/docs
        stdin_open: true
        tty: true
    
  6. Create Documentation Directory:

  7. Within the mkdocs directory, create another directory called docs. This will hold all your documentation files.

  8. Create MkDocs Configuration File:

  9. In the root of your mkdocs directory, create a file named mkdocs.yml.
  10. Add the following base structure to the mkdocs.yml file:

    site_name: Techdox Doc
    
    nav:
      - Home: index.md
      - About: about.md
    
    theme:
      name: 'material'
    
    • Feel free to customize the site_name, navigation (nav), and other configurations as needed.
  11. Start the MkDocs Container:

  12. Run docker-compose up -d from within the mkdocs directory. This command starts the MkDocs container in detached mode.

  13. Access MkDocs:

  14. Once the container is running, access your MkDocs site by navigating to http://<host-ip>:8005.
  15. You should see your MkDocs site with the Material theme, ready for further customization and document addition.

By following these steps, you will have a fully functional MkDocs site running in a Docker container, which you can access and edit as needed.

Example MkDocs Configuration (mkdocs.yml)

This example demonstrates how to configure an MkDocs site with subpages, plugins, and additional features.

site_name: Techdox Docs
nav:
  - Home: index.md
  - About: about.md
  - Docker Containers:
      - Overview: docker-containers.md
      - Adguard: adguard.md
      # Additional Docker container pages...
  - Networking:
      - Overview: networking-overview.md
      - GlusterFS: glusterfs.md
  # Additional sections...

theme:
  name: material
  logo: path/to/logo.png

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  # Additional Markdown extensions...
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.superfences
  # More pymdownx extensions...

extra:
  analytics:
    provider: google
    property: G-1XXXXXX

Youtube Video