Skip to content

Configuration Options Reference

Complete reference for all configuration options in mkdocs.yml.

Core Settings

Site Information

# Required
site_name: U.WIKI

# Recommended  
site_description: A modern, responsive wiki
site_author: Your Name
site_url: https://example.com

# Optional
copyright: Copyright © 2024 Your Name

Repository

# Link to source repository
repo_name: username/U.WIKI
repo_url: https://github.com/username/U.WIKI

# Edit button configuration
edit_uri: edit/main/docs/  # GitHub
# edit_uri: blob/main/docs/  # GitLab
# edit_uri: src/default/docs/  # Bitbucket

Build Directories

# Input/output directories
docs_dir: docs      # Default: docs
site_dir: site      # Default: site

# Exclude files from build
exclude_docs: |
  drafts/
  *.tmp
  .DS_Store

Theme Configuration

Basic Theme Settings

theme:
  name: material
  custom_dir: overrides  # Optional custom overrides
  language: en          # ISO 639-1 language code
  
  # Logo and icons
  logo: assets/logo.png  # or material/icon-name
  favicon: assets/favicon.png
  
  icon:
    logo: material/library
    repo: fontawesome/brands/github
    edit: material/pencil
    view: material/eye

Color Palette

theme:
  palette:
    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo     # Primary color
      accent: indigo      # Accent color
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    
    # Dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Available colors: red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange, brown, grey, blue-grey, black, white

Typography

theme:
  font:
    text: Roboto        # Body font
    code: Roboto Mono   # Code font
    
  # Or disable Google Fonts
  font: false

Theme Features

theme:
  features:
    # Navigation
    - navigation.instant          # Instant loading
    - navigation.instant.prefetch # Prefetch pages
    - navigation.instant.progress # Progress indicator
    - navigation.tracking         # URL tracking
    - navigation.tabs             # Tab navigation
    - navigation.tabs.sticky      # Sticky tabs
    - navigation.sections         # Collapsible sections
    - navigation.expand           # Expand all sections
    - navigation.path             # Breadcrumbs
    - navigation.prune           # Prune navigation tree
    - navigation.indexes         # Section index pages
    - navigation.top             # Back to top button
    - navigation.footer          # Previous/next footer
    
    # Table of contents
    - toc.follow                 # Follow scroll
    - toc.integrate             # Integrate in navigation
    
    # Search
    - search.suggest            # Search suggestions
    - search.highlight         # Highlight results
    - search.share            # Share search
    
    # Header
    - header.autohide        # Auto-hide header
    
    # Content
    - content.action.edit    # Edit button
    - content.action.view    # View source button
    - content.code.copy     # Copy button on code
    - content.code.select   # Select button on code
    - content.code.annotate # Code annotations
    - content.tabs.link    # Link content tabs
    - content.tooltips    # Tooltips
    
    # Announce
    - announce.dismiss    # Dismissible banner

Plugin Configuration

plugins:
  - search:
      lang: en              # Language
      separator: '[\s\-\.]+'  # Word separator regex
      min_search_length: 3  # Minimum query length
      prebuild_index: true  # Prebuild index
      indexing: 'full'      # full, sections, titles

Additional Plugins

plugins:
  # Table of contents
  - toc:
      permalink: true
      toc_depth: 3
  
  # Tags
  - tags:
      tags_file: tags.md
      tags_extra_files:
        compatibility:
          - compat.md
  
  # Social cards
  - social:
      cards: true
      cards_layout: default
      cards_color:
        fill: "#1e88e5"
        text: "#ffffff"
  
  # Minification
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      
  # Git information
  - git-revision-date-localized:
      enable_creation_date: true
      type: iso_datetime
      
  # Redirects
  - redirects:
      redirect_maps:
        old.md: new.md
        archive/page.md: current/page.md

Markdown Extensions

Python Markdown

markdown_extensions:
  # Core extensions
  - abbr              # Abbreviations
  - admonition        # Admonition blocks
  - attr_list         # Attribute lists
  - def_list          # Definition lists
  - footnotes         # Footnotes
  - md_in_html        # Markdown in HTML
  - meta              # Metadata
  - tables            # Tables
  - toc:              # Table of contents
      permalink: true
      permalink_title: Anchor link to this section
      toc_depth: 3
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

PyMdown Extensions

markdown_extensions:
  # Code and syntax
  - pymdownx.superfences:      # Code blocks
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.highlight:        # Syntax highlighting
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
      use_pygments: true
  - pymdownx.inlinehilite     # Inline code highlighting
  
  # Content enhancement
  - pymdownx.arithmatex:      # Math support
      generic: true
  - pymdownx.betterem:        # Better emphasis
      smart_enable: all
  - pymdownx.caret           # Superscript
  - pymdownx.critic          # Critic markup
  - pymdownx.details         # Collapsible blocks
  - pymdownx.emoji:          # Emoji
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons
  - pymdownx.keys           # Keyboard keys
  - pymdownx.mark          # Mark text
  - pymdownx.smartsymbols  # Smart symbols
  - pymdownx.snippets:    # Include snippets
      auto_append:
        - includes/abbreviations.md
  - pymdownx.tabbed:     # Content tabs
      alternate_style: true
      combine_header_slug: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:  # Task lists
      custom_checkbox: true
  - pymdownx.tilde     # Subscript

Simple Navigation

nav:
  - Home: index.md
  - About: about.md
  - Contact: contact.md

Nested Navigation

nav:
  - Home: index.md
  - Getting Started:
    - getting-started/index.md
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
  - User Guide:
    - guides/index.md
    - Creating Pages: guides/creating-pages.md
    - Markdown Syntax: guides/markdown-syntax.md
  - Reference:
    - reference/index.md
    - API: reference/api.md
    - Configuration: reference/config.md

Dynamic Navigation

# Use glob patterns
nav:
  - Home: index.md
  - Blog: blog/*.md
  - API: api/**/*.md

Extra Configuration

CSS and JavaScript

extra_css:
  - assets/stylesheets/custom.css
  - https://cdn.example.com/style.css

extra_javascript:
  - assets/javascripts/custom.js
  - https://cdn.example.com/script.js

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/username
      name: GitHub
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/username
      name: Twitter
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/username
      name: LinkedIn
    - icon: fontawesome/solid/envelope
      link: mailto:[email protected]
      name: Email

Analytics

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX
    
    # Or custom
    provider: custom
    # Add custom analytics in templates

extra:
  consent:
    title: Cookie consent
    description: >-
      We use cookies to recognize your visits and preferences.
    cookies:
      analytics:
        name: Google Analytics
        checked: true
      custom:
        name: Custom cookies
        checked: false
    actions:
      - accept
      - reject
      - manage

Version

extra:
  version:
    provider: mike
    default: latest

Status

extra:
  status:
    new: Recently added
    deprecated: Deprecated

Tags

extra:
  tags:
    HTML5: html
    JavaScript: js
    CSS: css

Validation

# Strict mode
strict: true

# Validation options
validation:
  nav:
    omitted_files: warn
    not_found: warn
    absolute_links: warn
  links:
    not_found: warn
    absolute_links: ignore
    unrecognized_links: ignore

Hooks

# Python hooks file
hooks:
  - mkdocs_hooks.py

# mkdocs_hooks.py
def on_pre_build(config):
    """Before building documentation."""
    pass

def on_files(files, config):
    """After files are collected."""
    return files

def on_nav(nav, config, files):
    """After navigation is created."""
    return nav

def on_page_read_source(page, config):
    """Before markdown is read."""
    return ""

def on_page_markdown(markdown, page, config, files):
    """After markdown is read."""
    return markdown

def on_page_content(html, page, config, files):
    """After HTML is rendered."""
    return html

def on_post_build(config):
    """After documentation is built."""
    pass

Environment Variables

# Use environment variables
site_name: !ENV [SITE_NAME, "Default Name"]
site_url: !ENV SITE_URL

# With defaults
extra:
  analytics:
    property: !ENV [ANALYTICS_ID, ""]

Complete Example

# Minimal functional configuration
site_name: U.WIKI
site_url: https://U.WIKI
site_description: Modern documentation wiki
site_author: Wiki Team

repo_name: username/U.WIKI
repo_url: https://github.com/username/U.WIKI
edit_uri: edit/main/docs/

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy

plugins:
  - search
  - tags

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - attr_list
  - md_in_html
  - toc:
      permalink: true

nav:
  - Home: index.md
  - Getting Started:
    - getting-started/index.md
    - Quick Start: getting-started/quick-start.md
  - Guides:
    - guides/index.md
    - Creating Pages: guides/creating-pages.md

Further Reading