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

- Skill: `vamseeachanta/mkdocs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vamseeachanta/mkdocs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamseeachanta/mkdocs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: vamseeachanta (https://skillmd.com/u/vamseeachanta)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vamseeachanta/mkdocs

---


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