MkDocs Configuration and Plugins

Purpose

The MkDocs configuration defines the theme, features, and plugins for the documentation site. We use the Material theme and have developed a custom plugin (lenient_builder) to handle invalid markdown gracefully when aggregating from multiple repositories.

MkDocs Configuration

The mkdocs.yml file configures:

• Theme: Material for MkDocs with dark mode support
• Features: Navigation tabs, sections, search suggestions, code copying
• Plugins: Search, tags, Mermaid diagrams, and our custom lenient builder
• Markdown Extensions: Syntax highlighting, superfences (for code blocks and diagrams)

Custom Plugin: Lenient Builder

Purpose

When aggregating documentation from 17+ GitHub organizations, we cannot control markdown quality. A single invalid file would normally crash the entire build, preventing all documentation from being published.

The lenient_builder plugin solves this by catching rendering errors and displaying a fallback error page instead of failing the build.

How It Works

The plugin uses a catch-all approach by monkey-patching MkDocs' internal _populate_page function:

1. Wraps the renderer - Intercepts page rendering with try/catch
2. Catches all exceptions - Any rendering error (invalid markdown, broken Mermaid, etc.)
3. Logs warnings - Records the error without stopping the build
4. Shows fallback - Displays a user-friendly error message on that specific page

Benefits

• Zero maintenance - No need to detect specific error types
• Build always succeeds - Site publishes even with some invalid pages
• Clear feedback - Authors see which pages failed and can fix them
• Minimal code - Simple, focused implementation

Configuration

In mkdocs.yml:

plugins:
  - lenient_builder:
      fallback_message: >-
        This page contains invalid markdown and could not be rendered. 
        Please check the source repository.

Other Plugins

• search - Full-text search across all documentation
• tags - Tag-based content organization and discovery
• mermaid2 - Renders Mermaid diagrams in code blocks

Local Development

To test MkDocs configuration changes locally:

source venv/bin/activate
pip install -e .  # Install lenient_builder plugin
mkdocs serve