mkdocs-material

name	mkdocs-material
description	MkDocs with Material theme expertise for Python-centric documentation. Configure navigation, plugins, multi-language support, PDF export, and advanced Material theme features.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
backlog-id	SK-003
metadata	{"author":"babysitter-sdk","version":"1.0.0"}
graph	{"domains":["domain:software-engineering"],"specializations":["specialization:technical-documentation"],"skillAreas":["skill-area:docs-as-code","skill-area:tutorial-design"],"roles":["role:technical-writer","role:documentation-engineer"]}

MkDocs/Material Skill

MkDocs with Material theme expertise for Python-centric documentation.

Capabilities

• Configure mkdocs.yml with Material theme features
• Set up navigation and table of contents
• Enable and configure MkDocs plugins (search, macros, mermaid)
• Admonition and code annotation usage
• Configure multi-language support
• Generate PDF export configurations
• Integrate with GitHub Pages deployment
• Enable blog and versioning features

Usage

Invoke this skill when you need to:

• Set up MkDocs with Material theme
• Configure advanced theme features
• Add plugins for extended functionality
• Set up multi-language documentation
• Enable versioning with mike

Inputs

Parameter	Type	Required	Description
action	string	Yes	init, configure, plugin, deploy
projectPath	string	Yes	Path to MkDocs project
config	object	No	Configuration options
plugins	array	No	Plugins to configure
locale	string	No	Language locale

Input Example

{
  "action": "configure",
  "projectPath": "./docs",
  "config": {
    "site_name": "My Documentation",
    "site_url": "https://docs.example.com",
    "theme": "material"
  },
  "plugins": ["search", "mermaid2"]
}

Project Configuration

mkdocs.yml

site_name: My Documentation
site_url: https://docs.example.com
site_description: Developer documentation for My Product
site_author: My Team

repo_name: my-org/my-project
repo_url: https://github.com/my-org/my-project
edit_uri: edit/main/docs/

theme:
  name: material
  language: en
  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
  
     
      
  
     
     
     
     
     
     
     
     
     
     
     
     
     
     
  
     


   
       
   
       
   
       
       
   
       


   
   
   
   
   
   
   
   
       
       
   
       
   
       
   
   
   
       
       
   
       
       
       
   
   
   
   
   
      
          
           
           
   
       
   
       
   


  
      
       
      
       
  
     
  
     
     
  
      
           


   


   


    
   
      
      
      
   
     
      
      
   
     
      
      
    
    

Admonitions

Standard Admonitions

!!! note "Custom Title"
    This is a note with a custom title.

!!! tip
    This is a helpful tip.

!!! warning
    This is a warning message.

!!! danger "Critical"
    This is a critical danger message.

!!! info
    This is an informational note.

!!! success
    This indicates success.

!!! question
    This poses a question.

!!! quote
    This is a quotation.

??? example "Collapsible Example"
    This content is collapsible (closed by default).

???+ example "Collapsible Example (Open)"
    This content is collapsible (open by default).

Code Annotations

Annotated Code Blocks

```python
import requests

# (1)!
response = requests.get(
    "https://api.example.com/users",
    headers={"Authorization": f"Bearer {token}"}  # (2)!
)

data = response.json()  # (3)!
```

1. Import the requests library for HTTP calls
2. Include authentication token in headers
3. Parse the JSON response

Content Tabs

Tabbed Content

=== "Python"
    ```python
    import requests
    response = requests.get("https://api.example.com")
    ```

=== "JavaScript"
    ```javascript
    const response = await fetch("https://api.example.com");
    ```

=== "cURL"
    ```bash
    curl https://api.example.com
    ```

Versioning with Mike

mike Configuration

# Deploy version
mike deploy --push --update-aliases 1.0 latest

# Set default version
mike set-default --push latest

# List versions
mike list

# Delete version
mike delete 0.9

Versioned Docs Structure

# mkdocs.yml
extra:
  version:
    provider: mike
    default: latest

Multi-language (i18n)

mkdocs.yml i18n

plugins:
  - i18n:
      default_language: en
      languages:
        - locale: en
          name: English
          build: true
        - locale: es
          name: Español
          build: true
        - locale: ja
          name: 日本語
          build: true
      nav_translations:
        es:
          Home: Inicio
          Getting Started: Empezando
        ja:
          Home: ホーム
          Getting Started: 始めよう

PDF Export

pdf-export Plugin

plugins:
  - pdf-export:
      verbose: true
      media_type: print
      combined: true
      combined_output_path: pdf/complete-documentation.pdf

Mermaid Diagrams

Mermaid Integration

```mermaid
sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database

    U->>A: Request
    A->>D: Query
    D-->>A: Result
    A-->>U: Response
```

Macros Plugin

Custom Macros

# mkdocs.yml
plugins:
  - macros:
      module_name: docs/macros

# docs/macros.py
def define_env(env):
    @env.macro
    def version():
        return "1.0.0"

    @env.macro
    def include_file(filename):
        with open(filename, 'r') as f:
            return f.read()

<!-- Usage in docs -->
Current version: {{ version() }}

{{ include_file("examples/config.yaml") }}

Workflow

1. Initialize project - Create MkDocs project structure
2. Configure theme - Set up Material theme
3. Add plugins - Enable required plugins
4. Structure navigation - Configure nav in mkdocs.yml
5. Add content - Write Markdown documentation
6. Build - Generate static site
7. Deploy - Publish to hosting

Dependencies

# requirements.txt
mkdocs>=1.5.0
mkdocs-material>=9.4.0
mkdocs-material-extensions>=1.3.0
mkdocs-minify-plugin>=0.7.0
mkdocs-git-revision-date-localized-plugin>=1.2.0
mkdocs-macros-plugin>=1.0.0
mike>=2.0.0

CLI Commands

# Create new project
mkdocs new my-docs

# Start development server
mkdocs serve

# Build static site
mkdocs build

# Deploy to GitHub Pages
mkdocs gh-deploy

# Deploy versioned docs with mike
mike deploy --push --update-aliases 1.0 latest

Best Practices Applied

• Use navigation tabs for top-level sections
• Enable instant loading for SPA experience
• Configure search suggestions
• Add code copy buttons
• Use admonitions for callouts
• Enable dark/light mode toggle
• Add social links in footer

References

• MkDocs: https://www.mkdocs.org/
• Material for MkDocs: https://squidfunk.github.io/mkdocs-material/
• PyMdown Extensions: https://facelessuser.github.io/pymdown-extensions/
• mike: https://github.com/jimporter/mike

Target Processes

• docs-as-code-pipeline.js
• docs-versioning.js
• knowledge-base-setup.js
• how-to-guides.js