Material MkDocs

Purpose: Documentation that simply works. Write your documentation in Markdown and create a professional static site for your Open Source or commercial project in minutes – searchable, customizable, more than 60 languages, for all devices.

Note

This is best deployed in tandem with the Git Repo Updater container in its own stack. Utilizing this will allow you to push commits to a repository to immediately (within 5 seconds) push changes into MKDocs without needing SSH/Portainer access to the server hosting MKDocs. If you don't have a GitHub account, consider deploying a Gitea container to host your own code repository! This all assumes you have already deployed Docker and Portainer.

Documentation / Pull Sequence¶

sequenceDiagram
    participant Gitea
    participant Git_Repo_Updater as Git-Repo-Updater
    participant MkDocs
    participant NTFY

    loop Every 5 seconds
        Git_Repo_Updater->>Gitea: Check for changes in repository
        alt Changes Detected
            Gitea->>Git_Repo_Updater: Notify change
            Git_Repo_Updater->>NTFY: Send change notification
            Git_Repo_Updater->>Gitea: Download data from repository
            Git_Repo_Updater->>MkDocs: Copy data to MkDocs
            MkDocs->>MkDocs: Reload and render webpages
        end
    end

Deploy Material MKDocs¶

docker-compose.yml

version: '3'

services:
  mkdocs:
    container_name: mkdocs
    image: squidfunk/mkdocs-material
    restart: always
    environment:
      - TZ=America/Denver
    ports:
      - "8000:8000"
    volumes:
      - /srv/containers/material-mkdocs/docs:/docs
    networks:
        docker_network:
          ipv4_address: 192.168.5.76
networks:
  docker_network:
    external: true

.env

N/A

Config Example¶

When you deploy MKDocs, you will need to give it a configuration to tell MKDocs how to structure itself. The configuration below is what I used in my deployment. This file is one folder level higher than the /docs folder that holds the documentation of the website.

/srv/containers/material-mkdocs/docs/mkdocs.yml

# Project information
site_name: Bunny Lab
site_url: https://docs.bunny-lab.io
site_author: Nicole Rappe
site_description: >-
  Server, Script, Workflow, and Networking Documentation
repo_url: https://git.bunny-lab.io/bunny-lab/docs
repo_name: bunny-lab/docs
edit_uri: _edit/main/

# Configuration
theme:
  name: material
  custom_dir: material/overrides
  features:
    - announce.dismiss
    - content.action.edit
#    - content.action.view
    - content.code.annotate
    - content.code.copy
    - content.code.select
    - content.tabs.link
    - content.tooltips
#    - header.autohide
    - navigation.expand
#    - navigation.footer
    - navigation.indexes
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.instant.progress
    - navigation.prune
    - navigation.sections
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
    - toc.follow
#    - toc.integrate ## If this is enabled, the TOC will appear on the left navigation menu.
  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/link
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: deep purple
      accent: deep purple
      toggle:
        icon: material/toggle-switch
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: deep purple
      toggle:
        icon: material/toggle-switch-off
        name: Switch to system preference
  font:
    text: Roboto
    code: Roboto Mono
  favicon: assets/favicon.png
  icon:
    logo: logo

# Plugins
plugins:
  - search:
      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
  - minify:
      minify_html: true

# Hooks
hooks:
  - material/overrides/hooks/shortcodes.py
  - material/overrides/hooks/translations.py

# Additional configuration
extra:
  status:
    new: Recently added
    deprecated: Deprecated

extra_css:
  - stylesheets/extra.css

# Extensions
markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
      toc_depth: 3
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      emoji_index: !!python/name:material.extensions.emoji.twemoji
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      normalize_issue_symbols: true
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets:
      auto_append:
        - includes/mkdocs.md
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

Cleaning up¶

When the server is deployed, it will come with a bunch of unnecessary documentation that tells you how to use it. You will want to go into the /docs folder, and delete everything except assets/favicon.png, schema.json, and /schema. These files are necessary to allow MKDocs to automatically detect and structure the documentation based on the file folder structure under /docs.