Documenting With Mkdocs

Documenting with MkDocs

Purpose

Comprehensive project documentation using MkDocs Material. Works for any project type: libraries, applications, services.

Structure

docs/
├── index.md                    # Landing page
├── getting-started/
│   ├── installation.md
│   └── quickstart.md
├── guides/
│   ├── architecture.md
│   └── core-concepts.md
├── reference/                  # Components/modules
│   └── feature-name.md
├── examples/
│   └── example-1.md
└── api/                        # Auto-generated (libraries)
    └── module.md

mkdocs.yml

site_name: Project Name
site_url: https://username.github.io/repo/
repo_url: https://github.com/username/repo

theme:
  name: material
  palette:
    - media: "(prefers-color-scheme)"
      scheme: default
      primary: indigo
      toggle:
        icon: material/brightness-7
        name: Dark mode
    - scheme: slate
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: Light mode
  features:
    - navigation.sections
    - content.code.copy
    - search.suggest

plugins:
  - search

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - admonition

nav:
  - Home: index.md
  - Getting Started:
      - Installation: getting-started/installation.md
      - Quick Start: getting-started/quickstart.md
  - Reference:
      - Feature: reference/feature.md

API Auto-Generation

Python (mkdocstrings):

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: true
            docstring_style: google

# pyproject.toml
[project.optional-dependencies]
docs = ["mkdocs-material>=9.5", "mkdocstrings[python]>=0.24"]

TypeScript:

npx typedoc --plugin typedoc-plugin-markdown --out docs/api

Rust/Go: Link to docs.rs or pkg.go.dev

Justfile Commands

# Serve docs locally
docs-serve:
    uv run mkdocs serve --dev-addr 0.0.0.0:8000

# Build docs
docs-build:
    uv run mkdocs build

# Deploy to GitHub Pages
docs-deploy:
    uv run mkdocs gh-deploy --force

GitHub Pages

.github/workflows/docs.yml:

name: Deploy Documentation

on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yml']

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Landing Page Template

# Project Name

**Brief tagline**

One-paragraph description.

## Key Features

- **Feature 1** - Description
- **Feature 2** - Description

## Quick Example

\`\`\`python
# Complete, runnable example (< 20 lines)
\`\`\`

## Installation

\`\`\`bash
pip install project-name
\`\`\`

## Next Steps

- [Installation Guide](getting-started/installation.md)
- [Quick Start](getting-started/quickstart.md)

Content Guidelines

Guides:

• Start with "Why" (motivation)
• Include diagrams
• Complete code examples
• Link to API docs

Reference:

• Feature purpose
• Parameters/options
• Code examples
• Common patterns

Quality:

• docs-build succeeds without warnings
• All internal links work
• Code examples tested
• Dark/light mode work