Skip to content

User Documentation (MkDocs)

Purpose

Configuration and guidelines for generating user-facing documentation (guides, tutorials, reference) using MkDocs with Material theme. This directory contains the build configuration, not the documentation content.

Contents

Configuration

  • mkdocs.yml - Main MkDocs configuration
  • Material theme setup
  • Navigation structure
  • Markdown extensions
  • Plugin configuration

Guidelines

  • docs_structure.md - Documentation organization and content strategy
  • markdown_style.md - Markdown writing and formatting standards

Quick Start

Prerequisites

# Install Python 3.8+ (if not installed)
winget install Python.Python.3.11

# Install MkDocs and Material theme
pip install mkdocs mkdocs-material

# Install additional plugins
pip install mkdocs-minify-plugin

# Verify installation
mkdocs --version

Build Documentation

# From this directory
cd "2 - FOUNDATION/03_INFRA/03_11_documentation_platform/03_11_01_user_documentation"

# Build static site
mkdocs build -f mkdocs.yml

# Serve locally with live reload
mkdocs serve -f mkdocs.yml

# Open browser to http://localhost:8000

Using the Master Script

# From automation directory
cd ../03_11_05_documentation_automation
.\generate_docs.ps1 -Target user

Configuration Overview

Key Settings in mkdocs.yml

Setting Value Purpose
site_name "AudioLab Documentation" Site title
theme.name material Use Material theme
docs_dir ../../../../10_DOCUMENTATION/user_guide Source content location
site_dir ../../../../var/docs/user Build output location
plugins search, minify Search and optimization

Material Theme Features Enabled

  • Navigation:
  • Instant loading (SPA-like experience)
  • Top-level tabs
  • Expandable sections

  • Back-to-top button

  • Search:

  • Full-text search
  • Search suggestions

  • Highlight results

  • Content:

  • Code copy buttons
  • Code annotations
  • Content tabs
  • Light/dark mode toggle

Markdown Extensions Enabled

  • Admonitions: Note, warning, tip callouts
  • Code Highlighting: Syntax highlighting with line numbers
  • Tables: Enhanced table formatting
  • Math: LaTeX math formulas via MathJax
  • Mermaid: Diagrams as code
  • Emoji: GitHub-style emoji :smile:
  • Task Lists: - [ ] checkbox lists
  • Footnotes: Reference notes

Content Location

Source Files

Documentation content is in 10_DOCUMENTATION/user_guide/:

10_DOCUMENTATION/user_guide/
├── index.md                    # Homepage
├── getting-started/            # New user guides
├── user-guide/                 # Feature documentation
├── tutorials/                  # Step-by-step tutorials
├── reference/                  # Technical reference
├── best-practices/             # Guidelines
├── faq.md
├── glossary.md
├── contributing.md
└── changelog.md

Why separate? - Configuration (here) vs. content (10_DOCUMENTATION) - Allows documentation to evolve independently - Easier to manage permissions and workflows

Build Output

Generated documentation goes to var/docs/user/:

var/docs/user/
├── index.html
├── getting-started/
├── user-guide/
├── assets/
│   ├── stylesheets/
│   ├── javascripts/
│   └── images/
└── search/
    └── search_index.json

Defined in mkdocs.yml nav: section:

  1. Home - Landing page
  2. Getting Started - Installation, quick start, first plugin
  3. User Guide - Core concepts and features
  4. Tutorials - Hands-on learning
  5. Reference - API docs, architecture
  6. Best Practices - Guidelines and patterns
  7. FAQ, Glossary, Contributing, Changelog

Update nav: in mkdocs.yml when adding/removing pages.

Customization

Change Theme Colors

Edit mkdocs.yml: 

theme:
  palette:
    primary: indigo      # Change to: blue, green, red, etc.
    accent: blue         # Accent color for links

Add Custom CSS

  1. Create 10_DOCUMENTATION/user_guide/stylesheets/extra.css
  2. Edit mkdocs.yml: 
    extra_css:
  - stylesheets/extra.css

Add Custom JavaScript

  1. Create 10_DOCUMENTATION/user_guide/javascripts/extra.js
  2. Edit mkdocs.yml: 
    extra_javascript:
  - javascripts/extra.js

Add Logo/Favicon

  1. Place files in 10_DOCUMENTATION/user_guide/assets/
  2. Edit mkdocs.yml: 
    theme:
  logo: assets/logo.png
  favicon: assets/favicon.png

Writing Documentation

Creating New Pages

  1. Create markdown file in 10_DOCUMENTATION/user_guide/ 

    ---
title: My New Page
description: Page description
---

# My New Page

Content here...

  2. Add to navigation in mkdocs.yml: 

    nav:
  - User Guide:
    - My New Page: user-guide/my-new-page.md

  3. Preview changes: 

    mkdocs serve

Content Guidelines

See: docs_structure.md for organization strategy See: markdown_style.md for formatting standards

Quick tips: - Use admonitions for notes/warnings - Include code examples with syntax highlighting - Add diagrams with Mermaid - Link to related pages - Keep paragraphs short (3-5 sentences)

Code Examples

```cpp
#include <audiolab/AudioBuffer.hpp>

void process(audiolab::AudioBuffer<float>& buffer) {
    // Apply gain to all channels
    for (size_t ch = 0; ch < buffer.getNumChannels(); ++ch) {
        float* data = buffer.getChannelData(ch);
        for (size_t i = 0; i < buffer.getNumSamples(); ++i) {
            data[i] *= 0.5f;
        }
    }
}
```

Diagrams

```mermaid
graph LR
    A[Input] --> B[Process]
    B --> C[Output]
```

Validation

Build Errors

# Strict mode (fails on warnings)
mkdocs build --strict

# Install link checker
pip install mkdocs-linkcheck

# Add to mkdocs.yml plugins:
# - linkcheck

# Build (will check links)
mkdocs build

Spell Check

# Install cSpell
npm install -g cspell

# Check documentation
cspell "10_DOCUMENTATION/**/*.md"

Deployment

Static Site Generation

# Build production site
mkdocs build -f mkdocs.yml --strict

# Output in var/docs/user/
# Copy to web server or CDN

GitHub Pages

# Deploy to gh-pages branch
mkdocs gh-deploy

Docker

# Use existing MkDocs service from containerization
cd "../../03_05_containerization/03_06_06_mkdocs_service"
docker-compose up -d

CI/CD Integration

GitHub Actions

name: Build Documentation

on:
  push:
    branches: [main]
    paths:
      - '10_DOCUMENTATION/**'
      - '2 - FOUNDATION/03_INFRA/03_11_documentation_platform/**'

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install mkdocs mkdocs-material mkdocs-minify-plugin

      - name: Build documentation
        run: |
          cd "2 - FOUNDATION/03_INFRA/03_11_documentation_platform/03_11_01_user_documentation"
          mkdocs build --strict

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./var/docs/user

Troubleshooting

MkDocs Not Found

# Ensure Python and pip are in PATH
python --version
pip --version

# Reinstall MkDocs
pip install --upgrade mkdocs mkdocs-material

Build Warnings

# Run with verbose output
mkdocs build --verbose

# Common issues:
# - Missing files in nav
# - Broken links
# - Invalid front matter

Serve Errors

# Specify different port if 8000 is taken
mkdocs serve -a localhost:8001

# Check docs_dir path in mkdocs.yml
# Must be relative to mkdocs.yml location

Theme Not Loading

# Reinstall Material theme
pip install --upgrade mkdocs-material

# Verify in mkdocs.yml:
# theme:
#   name: material

Performance

Build Time Optimization

  • Use mkdocs build --dirty for incremental builds (dev only)
  • Enable minify plugin to reduce file sizes
  • Optimize images before adding to docs

Search Optimization

  • Use descriptive headings
  • Add front matter descriptions
  • Include relevant keywords
  • Keep titles concise

References

Documentation

Style Guides

AudioLab Docs

Maintenance

Regular Tasks

  • Update navigation when adding/removing pages
  • Check for broken links monthly
  • Update screenshots when UI changes
  • Review and refresh old content quarterly
  • Update theme and plugins for security

Version Updates

# Update all dependencies
pip install --upgrade mkdocs mkdocs-material mkdocs-minify-plugin

# Test after updates
mkdocs build --strict
mkdocs serve

Support