mkdocs
Build professional project documentation with MkDocs and Material theme. Covers site configuration, navigation, plugins, search optimization, versioning with mike, and deployment to GitHub Pages.
Best use case
mkdocs is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Build professional project documentation with MkDocs and Material theme. Covers site configuration, navigation, plugins, search optimization, versioning with mike, and deployment to GitHub Pages.
Teams using mkdocs should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/mkdocs/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How mkdocs Compares
| Feature / Agent | mkdocs | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Build professional project documentation with MkDocs and Material theme. Covers site configuration, navigation, plugins, search optimization, versioning with mike, and deployment to GitHub Pages.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Mkdocs
## When to Use This Skill
### USE When
- Building project documentation for open source or internal projects
- Need a fast, searchable static documentation site
- Want beautiful Material Design without custom CSS
- Require multi-version documentation (v1.x, v2.x, etc.)
- Deploying documentation to GitHub Pages, GitLab Pages, or Netlify
- Working with Python projects that need docs alongside code
- Need admonitions, code tabs, and content formatting
- Want simple Markdown-based documentation workflow
- Require offline-capable documentation
- Building API documentation alongside guides
### DON'T USE When
- Need complex React components in docs (use Docusaurus)
- Require auto-generated Python API docs (use Sphinx)
- Building single-page documentation (use simple HTML)
- Need document format conversion (use Pandoc)
- Require collaborative real-time editing (use GitBook)
- Building slide presentations (use Marp)
## Prerequisites
### Installation
```bash
# Using pip
pip install mkdocs mkdocs-material
# Using uv (recommended)
uv pip install mkdocs mkdocs-material
# With common plugins
pip install mkdocs mkdocs-material \
mkdocs-minify-plugin \
*See sub-skills for full details.*
### System Requirements
- Python 3.8 or higher
- pip or uv package manager
- Git (for git-revision plugin and mike)
- Node.js (optional, for social cards)
## Prerequisites
- Prerequisite 1
- Prerequisite 2
## Version History
### v1.0.0 (2026-01-17)
- Initial skill creation
- Material for MkDocs theme configuration
- Plugin ecosystem documentation
- GitHub Pages deployment workflows
- Versioning with mike
- Mermaid diagrams integration
- Custom CSS/JS extensions
- Best practices and troubleshooting
## Sub-Skills
- [1. Project Initialization (+1)](1-project-initialization/SKILL.md)
- [3. Navigation Structure (+2)](3-navigation-structure/SKILL.md)
- [Integration with Python Package (+2)](integration-with-python-package/SKILL.md)
- [1. Documentation Structure (+1)](1-documentation-structure/SKILL.md)
- [Examples](examples/SKILL.md)
- [Common Issues (+1)](common-issues/SKILL.md)
## Sub-Skills
- [Note](note/SKILL.md)
- [Tip](tip/SKILL.md)
- [Warning](warning/SKILL.md)
- [Danger](danger/SKILL.md)
- [Example](example/SKILL.md)
- [Info](info/SKILL.md)
- [Success](success/SKILL.md)
- [Question](question/SKILL.md)
- [Quote](quote/SKILL.md)
- [Collapsible Admonitions](collapsible-admonitions/SKILL.md)
- [6. Code Blocks with Features](6-code-blocks-with-features/SKILL.md)
- [Basic Code Block](basic-code-block/SKILL.md)
- [With Title](with-title/SKILL.md)
- [Line Numbers](line-numbers/SKILL.md)
- [Line Highlighting](line-highlighting/SKILL.md)
- [Line Number Start](line-number-start/SKILL.md)
- [Code Annotations](code-annotations/SKILL.md)
- [Tabbed Code Blocks](tabbed-code-blocks/SKILL.md)
- [7. Mermaid Diagrams](7-mermaid-diagrams/SKILL.md)
- [Flowchart](flowchart/SKILL.md)
- [Sequence Diagram](sequence-diagram/SKILL.md)
- [Class Diagram](class-diagram/SKILL.md)
- [State Diagram](state-diagram/SKILL.md)
- [Entity Relationship](entity-relationship/SKILL.md)
- [8. Plugin Configuration (+4)](8-plugin-configuration/SKILL.md)
- [Subsection 1.1](subsection-11/SKILL.md)
- [Section 2](section-2/SKILL.md)
- [3. Abbreviations (+2)](3-abbreviations/SKILL.md)
- [Related Resources](related-resources/SKILL.md)Related Skills
baoyu-article-illustrator
Article illustrations: type × style × palette consistency.
vscode-extensions
VS Code productivity optimization with essential extensions, settings sync, profiles, keybindings, snippets, and workspace configuration
git-advanced
Advanced git workflows including rebase, worktrees, bisect, hooks, and monorepo patterns
docker
Complete Docker containerization patterns with multi-stage builds for development and production workflows
elite-frontend-ux
Create distinctive, production-grade frontend interfaces with expert-level UX design. Use when building SaaS dashboards, landing pages, marketing sites, React/Vue components, HTML/CSS layouts, or any web UI. Combines bold aesthetic direction with systematic design tokens, WCAG accessibility, conversion optimization, and Tailwind/React best practices. Produces polished, memorable interfaces that avoid generic AI aesthetics while meeting professional standards. type: reference
sphinx
Generate comprehensive Python documentation with Sphinx. Covers autodoc for API extraction, Napoleon for Google/NumPy docstrings, intersphinx for cross-references, and multiple output formats including HTML, PDF, and ePub.
pandoc
Universal document converter for transforming Markdown to PDF, DOCX, HTML, LaTeX, and 40+ other formats. Covers templates, filters, citations with BibTeX/CSL, and batch conversion automation scripts.
marp
Create professional Markdown-based slide presentations with Marp. Covers themes, directives, speaker notes, presenter view, and export to PDF, HTML, and PPTX formats. Includes VS Code integration, CLI usage, and CI/CD automation.
docusaurus
Build modern documentation websites with Docusaurus. Covers docs, blog, pages, versioning, i18n, search integration, and deployment patterns. React-based with MDX support for interactive documentation.
slack-api
Slack bot development and workspace automation using Web API, Events API, Socket Mode, and Block Kit for building interactive messaging applications
miro-api
Miro whiteboard automation using REST API v2 and Python SDK for creating boards, frames, shapes, connectors, and collaborative visual workflows
calendly-api
Calendly scheduling automation using REST API v2 for managing event types, availability, bookings, webhooks, and scheduling workflows