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

# 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)