What is Material for MkDocs?

Material for MkDocs is a popular, customizable theme for building modern, responsive, and visually appealing documentation websites using MkDocs. MkDocs is a static site generator designed for creating project documentation with Markdown files. Material for MkDocs enhances this experience by providing an opinionated design inspired by Google's Material Design principles. (ChatGPT)

Sources

I honestly don't remember where most of this stuff came from. Lots from the official documentation (linked above), some from James Willett and a lot of back and forth with ChatGPT.

docker-compose.yml

version: '3.8'
services:
  mkdocs:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: mkdocs
    ports:
      - "8005:8000"
    volumes:
      - /volume1/docker/mkdocs:/docs:rw
    stdin_open: true
    tty: true
    #command: /usr/local/bin/mkdocs serve --reload -a 0.0.0.0:8000

Dockerfile

FROM squidfunk/mkdocs-material

RUN pip install --upgrade \
    mkdocs \
    mkdocs-material \
    mkdocs-exclude \
    mkdocs-material-extensions \
    mkdocs-minify-plugin \
    mkdocs-git-authors-plugin \
    mkdocs-git-committers-plugin \
    mkdocs-git-revision-date-localized-plugin \
    "mkdocs-material[imaging]" \
    pillow \
    cairosvg

mkdocs.yml

site_name: steili.com
site_url: https://steili.com
site_description: Musings, Findings and Tech
site_author: Brandon

plugins:
  - privacy
  - search
  - social:
      cards_layout: default/invert
      cards_layout_options:
        background_color: "#2E2E2E"  # Dark gray background
        color: "#FFFFFF"            # White text
        font_family: Atkinson Hyperlegible
extra_javascript:
    - javascripts/extra.js

extra_css:
    - extra.css
#    - css/logo-switch.css
    - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css

theme:
  name: material
  custom_dir: docs/custom_theme
  favicon: assets/favicon.ico
  features:
    # Navigation
    - navigation.instant
    - navigation.instant.progress
    - navigation.tracking
    - navigation.path
    - navigation.prune
    - navigation.footer

    # Copy Code Blocks
    - content.code.copy
    - content.code.select

    #search
    - search.suggest

    # Table of Contents
    - toc.follow

    # Search
    - search.suggest
    - search.highlight
  icon:
    # Custom repo icon https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#repository-icon
    repo: fontawesome/brands/github
  copyright: Copyright © 2025 steili.com
  logo: assets/logo-dark.svg
  font:
    text: Atkinson Hyperlegible
    code: Roboto Mono

  palette:
    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: white
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: blue grey
      accent: deep orange
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

extra:
  social:
    - icon: fontawesome/solid/file-lines-regular # Use FontAwesome's class for the "file-alt" icon
      link: https://drive.google.com/file/d/1baUHBdyPTTu2d0v2REC0MryzZuo1UpTa/view      # Point to your resume
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/brandonsteili
    - icon: fontawesome/brands/bluesky
      link: https://bsky.app/profile/brandonsteili.bsky.social
#  consent:
#    title: Cookie consent
#    description: >- 
#      We use cookies to recognize your repeated visits and preferences, as well
#      as to measure the effectiveness of our documentation and whether users
#      find what they're searching for. With your consent, you're helping us to
#      make our documentation better.


markdown_extensions:
  - abbr
  - admonition
  - pymdownx.arithmatex:
      generic: true
  - attr_list
  - md_in_html
  - pymdownx.blocks.caption
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

extra.css

/* Light theme logo */
body[data-md-color-scheme="default"] #logo {
    content: url("assets/logo-light.svg");
}

/* Dark theme logo */
body[data-md-color-scheme="slate"] #logo {
    content: url("assets/logo-dark.svg");
}