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:

Create a New Directory.
Create a new directory on your host system for your MkDocs container. You can name it mkdocs or any other name of your choice.
Docker Compose File.
Inside this new directory, create a docker-compose.yml file.

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

Create Documentation Directory.
Within the mkdocs directory, create another directory called docs. This will hold all your documentation files.
Create MkDocs Configuration File.
In the root of your mkdocs directory, create a file named mkdocs.yml.
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.
Start the MkDocs Container.
Run docker compose up -d from within the mkdocs directory. This command starts the MkDocs container in detached mode.
Access MkDocs.
Once the container is running, access your MkDocs site by navigating to http://:8005.
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...