Editing mkdocs.yml

The mkdocs.yml file is the central configuration file for the documentation site. It controls the site name, theme, navigation, extensions, and plugins. Changes to this file can break the entire site if formatting is incorrect.

YAML Formatting Rules

mkdocs.yml uses YAML syntax, which is sensitive to indentation and special characters.

Indentation

YAML uses spaces only (never tabs) for indentation. The standard is 2 spaces per level:

# Correct - 2-space indentation
theme:
  name: material
  features:
  - navigation.top
  - search.highlight

# WRONG - tab indentation (will cause a parse error)
theme:
    name: material

Tabs Will Break the Build

If your editor inserts tabs instead of spaces, the mkdocs serve command will fail with a YAML parse error. Configure your editor to use spaces for .yml files.

Colons in Values

YAML uses colons (:) to separate keys from values. If a value itself contains a colon, you must wrap the entire value in quotes:

# WRONG - the colon in the title breaks YAML parsing
nav:
  - Application Setup: configuration/applications.md#application-create-and-import
  - ERP Import Builder: administration/erp-import.md#erp-import-builder

# CORRECT - quotes around values containing colons
nav:
  - "Application Setup: Overview": configuration/applications.md

In the EPMware mkdocs.yml, nav entries that reference anchors with colons in the title must be quoted:

nav:
  - "Application Setup": configuration/applications.md#application-create-and-import

When Quotes Are Required

You only need quotes when the nav entry title contains a colon. File paths with # anchors do not need quotes by themselves — it is the colon in the display text that triggers the issue.

The nav section defines the sidebar navigation. Here is the pattern used in the EPMware guides:

nav:
  - Home:
    - index.md

  - Configuration:
    - configuration/index.md
    - Infrastructure:
      - configuration/infrastructure.md
      - Servers: configuration/infrastructure.md#servers
    - Applications:
      - configuration/applications.md
      - "Application Setup": configuration/applications.md#application-create-and-import

Create the .md file in the correct directory.
Add an entry under the appropriate section in nav:

nav:
  - Configuration:
    - configuration/index.md
    - Infrastructure:
      - configuration/infrastructure.md
    - New Page Title: configuration/new-page.md    # Add this line

Run mkdocs serve to verify the page appears in navigation.

Adding a New Section

To add an entirely new top-level section:

nav:
  - Existing Section:
    - existing/index.md

  - New Section:                    # Add this block
    - new-section/index.md
    - "Sub Page": new-section/sub-page.md

You can create nav entries that link to specific sections within a page:

- Security:
  - security/index.md
  - Security Model: security/#security-model
  - Security Rules: security/#security-rules

When the page is an index.md, the anchor path uses the folder name followed by /#anchor. When the page is a named file, use the full path: configuration/applications.md#section-name.

Commenting Out Nav Entries

To temporarily remove a nav entry without deleting it, prefix the line with #:

nav:
  - Configuration:
    - configuration/index.md
    # - Temporarily Hidden: configuration/hidden-page.md

Theme Configuration

The theme section controls the visual appearance:

theme:
  name: material
  palette:
    - scheme: default
      primary: blue
      accent: orange
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: blue
      accent: orange
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Do Not Change Theme Settings Casually

Theme changes affect the entire site. Changing primary or accent colors, or removing features, will alter the look and behavior of every page. Coordinate theme changes with the team.

Feature Flags

The features list controls MkDocs behaviors:

features:
- navigation.top          # "Back to top" button
- navigation.tracking     # URL updates as you scroll
- navigation.indexes      # index.md serves as section page
- search.highlight        # Highlight search terms on page
- search.share            # Shareable search links
- search.suggest          # Search autocomplete
- content.code.copy       # Copy button on code blocks
- content.tooltips        # Tooltip support
- navigation.footer       # Previous/Next page links
- toc.follow              # TOC scrolls with content
- toc.integrate           # TOC in left sidebar

Extensions

Markdown extensions add features like admonitions, tables, icons, and code fencing:

markdown_extensions:
  - admonition              # Note/warning/tip boxes
  - pymdownx.details        # Collapsible sections
  - pymdownx.superfences    # Fenced code blocks, Mermaid diagrams
  - attr_list               # Add HTML attributes to elements
  - md_in_html              # Markdown inside HTML blocks
  - tables                  # Table support
  - footnotes               # Footnote support
  - pymdownx.emoji:         # Material Design icons
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

pymdownx.emoji Configuration

The pymdownx.emoji extension is what enables :material-*: icons throughout the documentation. The two sub-properties (emoji_index and emoji_generator) must use the exact !!python/name: syntax shown above. Do not modify these values.

Plugins

plugins:
  - search:
      lang: en
  - glightbox:               # Image lightbox (click to zoom)
      touchNavigation: true
      loop: false
      effect: zoom

The search plugin is built into MkDocs. The glightbox plugin provides click-to-zoom functionality for images and must be installed separately (pip install mkdocs-glightbox).

Validating Changes

After editing mkdocs.yml:

Save the file.
Run mkdocs serve — if there are YAML syntax errors, the command will fail with an error message indicating the line number.
If the server starts, check the terminal output for any warnings (missing files, broken nav references).
Browse the site to verify navigation and page rendering.

Editing mkdocs.yml

YAML Formatting Rules

Indentation

Colons in Values

Navigation Structure

Adding a New Page to Navigation