name: agent-ops-mkdocs description: "MkDocs documentation site management: initializing, updating, building, and deploying" category: docs invokes: [agent-ops-state] invoked_by: [agent-ops-docs] state_files: read: [constitution.md] write: [focus.md]

agent-ops-mkdocs

Skill for managing MkDocs documentation sites: initializing, updating, building, and deploying.

Purpose

Provide documentation site management capabilities:

1. Initialize MkDocs site from template
2. Add/update documentation pages
3. Generate navigation from directory structure
4. Build and preview locally
5. Deploy to GitHub Pages

When to Use

• Setting up project documentation
• Adding new documentation pages
• Updating site configuration
• Deploying documentation updates

Workflow Overview

flowchart LR
    A[Init] --> B[Add Pages]
    B --> C[Build]
    C --> D[Preview]
    D --> E[Deploy]

Commands

Initialize Site

Set up a new MkDocs site with Material theme.

Input:

• Project name
• Site URL (optional)
• Theme options (optional)

Process:

1. Create mkdocs.yml with Material theme configuration
2. Create docs/ directory structure
3. Create docs/index.md home page
4. Add recommended extensions (admonition, tabs, mermaid)

Output:

mkdocs.yml
docs/
├── index.md
├── getting-started.md
└── assets/
    └── .gitkeep

Example:

Initialize MkDocs documentation for this project

Add Page

Add a new documentation page.

Input:

• Page title
• Section (optional)
• Content or template

Process:

1. Create markdown file in appropriate location
2. Update nav in mkdocs.yml
3. Add basic structure (title, sections)

Example:

Add a page called "API Reference" in the reference section

Generate Navigation

Auto-generate nav structure from docs/ directory.

Process:

1. Scan docs/ directory recursively
2. Extract titles from markdown files
3. Build nav tree
4. Update mkdocs.yml

Example:

Update mkdocs navigation from directory structure

Build Site

Build the static documentation site.

Process:

1. Run mkdocs build
2. Report any warnings/errors
3. Output to site/ directory

Example:

Build the documentation site

Preview Site

Start local development server.

Process:

1. Run mkdocs serve
2. Report URL (typically http://localhost:8000)
3. Watch for changes

Example:

Preview the documentation locally

Deploy to GitHub Pages

Deploy documentation to GitHub Pages.

Process:

1. Build site with mkdocs build --strict
2. Deploy with mkdocs gh-deploy
3. Or use GitHub Actions workflow

Example:

Deploy documentation to GitHub Pages

Configuration Templates

Minimal mkdocs.yml

site_name: Project Name
docs_dir: docs
site_dir: site

theme:
  name: material

plugins:
  - search

nav:
  - Home: index.md

Full Featured mkdocs.yml

site_name: Project Name
site_url: https://username.github.io/project/
site_description: Project description
docs_dir: docs
site_dir: site
use_directory_urls: true

repo_name: username/project
repo_url: https://github.com/username/project

theme:
  name: material
  features:
    - navigation.sections
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.expand
    - navigation.top
    - content.code.copy
    - content.code.annotate
    - search.suggest
    - search.highlight
  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

plugins:
  - search

markdown_extensions:
  - admonition
  - footnotes
  - tables
  - toc:
      permalink: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - attr_list
  - md_in_html

nav:
  - Home: index.md
  - Getting Started: getting-started.md

Page Templates

Standard Page

# Page Title

Brief description of the page content.

## Section 1

Content...

## Section 2

Content...

## See Also

- [Related Page](related.md)

API Reference Page

# API Reference

## Endpoints

### GET /resource

Description of endpoint.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | Resource identifier |

**Response:**

```json
{
  "id": "123",
  "name": "Example"
}

POST /resource

...

### Tutorial Page

```markdown
# Tutorial: Feature Name

Learn how to use Feature Name in 10 minutes.

## Prerequisites

- Requirement 1
- Requirement 2

## Step 1: Setup

First, we need to...

## Step 2: Configuration

Next, configure...

## Step 3: Usage

Now you can...

## Summary

In this tutorial, you learned:

- Point 1
- Point 2

## Next Steps

- [Advanced Usage](advanced.md)

Directory Structure Patterns

Simple Project

docs/
├── index.md
├── getting-started.md
├── configuration.md
└── api-reference.md

Medium Project

docs/
├── index.md
├── getting-started/
│   ├── installation.md
│   ├── quickstart.md
│   └── first-steps.md
├── guides/
│   ├── basic-usage.md
│   └── advanced-usage.md
├── reference/
│   ├── api.md
│   └── configuration.md
└── about/
    ├── changelog.md
    └── contributing.md

Large Project

docs/
├── index.md
├── getting-started/
│   ├── index.md
│   ├── installation.md
│   ├── quickstart.md
│   └── tutorial.md
├── concepts/
│   ├── index.md
│   ├── architecture.md
│   └── terminology.md
├── guides/
│   ├── index.md
│   ├── user-guide.md
│   ├── admin-guide.md
│   └── developer-guide.md
├── reference/
│   ├── index.md
│   ├── api/
│   ├── cli/
│   └── configuration/
├── deployment/
│   ├── index.md
│   ├── docker.md
│   └── kubernetes.md
└── about/
    ├── changelog.md
    ├── roadmap.md
    └── contributing.md

GitHub Actions Integration

Deployment Workflow

# .github/workflows/docs.yml
name: Deploy Documentation

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

permissions:
  contents: write
  pages: write
  id-token: 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 pymdown-extensions
      - run: mkdocs gh-deploy --force

Dependencies

Required Python packages:

pip install mkdocs mkdocs-material pymdown-extensions

Or with uv:

uv add --dev mkdocs mkdocs-material pymdown-extensions

Validation

Before deploying, validate:

1. Build succeeds: mkdocs build --strict
2. Links work: No broken internal links
3. Images load: All referenced images exist
4. Navigation correct: All pages accessible

Integration with Other Skills

Troubleshooting

"mkdocs: command not found"

Install MkDocs:

pip install mkdocs mkdocs-material

"Theme 'material' not found"

Install Material theme:

pip install mkdocs-material

"Mermaid diagrams not rendering"

Ensure superfences extension is configured correctly in mkdocs.yml.

"Navigation not updating"

Regenerate nav:

Update mkdocs navigation from directory structure

"GitHub Pages 404"

Check:

• site_url matches your GitHub Pages URL
• use_directory_urls: true is set
• gh-pages branch exists