How to setup MkDocs (with Docker & Caddy)

Ready to use

Description

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation.

Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Files and Folders

Create the folder structure.

mkdir -p ~/services/mkdocs/docs
touch ~/services/mkdocs/mkdocs.yml

Add the following content to the mkdocs.yml file:

site_name: AKD's 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: logo/logo.png
  features:
    - content.code.copy

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
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  # More pymdownx extensions...

Note

This is just an example file.
After you're setup is up and running, you'll be able to change it to your actual documentation.

We'll also add a couple of sample pages.

touch ~/services/mkdocs/docs/{index.md,about.md}

nano ~/services/mkdocs/docs/index.md

Add the following content to index.md:

Hello World!

!!! success "Yay!"

    It works

What [about](./about.md) you?

nano ~/services/mkdocs/docs/about.md

And the following to about.md:

What about me?
Go [home](./index.md)!

Docker

Add the mkdocs section to your docker-compose.yml file:

  mkdocs:
    image: squidfunk/mkdocs-material
    ports:
      - "8005:8000"
    volumes:
      - ./mkdocs:/docs
    stdin_open: true
    tty: true
    restart: unless-stopped

Tip

stdin_open: true and tty: true allow interactive processes, which is useful for live reloading during documentation development.

Download and start mkdocs:
```
docker compose up -d mkdocs
```

Try it out

See if you can access the mkdocs web interface at http://your_server_IP:8005.

Troubleshooting

If it doesn't work, see the troubleshooting guide.

Links

Official site

Github page

https://docs.techdox.nz/mkdocs/

https://readthedocs.vinczejanos.info/Blog/2021/10/01/How_to_use_MKdocs/

https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage