agent-ops-mkdocs

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  
      
       
       
      
         
            


   


   
   
   
   
       
   
      
          
           
           
   
   
       
       
   
       
   
       
       
   
   


    
    

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

Skill	Integration
agent-ops-docs	Documentation content management
agent-ops-validation	Include docs build in validation
agent-ops-git	Commit documentation changes

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