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
  font:
    text: Roboto
    code: Roboto Mono
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.expand
    - navigation.indexes
    - navigation.top
    - search.suggest
    - search.highlight
    - search.share
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
  icon:
    repo: fontawesome/brands/github

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
  - minify:
      minify_html: true
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
  - tags:
      tags_file: tags.md

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      toc_depth: 3
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/my-org
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/my-org
  version:
    provider: mike
  analytics:
    provider: google
    property: G-XXXXXXXXXX
  consent:
    title: Cookie consent
    description: We use cookies to improve your experience.

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
    - Configuration: getting-started/configuration.md
  - User Guide:
    - user-guide/index.md
    - Authentication: user-guide/authentication.md
    - API Usage: user-guide/api-usage.md
  - API Reference:
    - api/index.md
    - Client: api/client.md
    - Resources: api/resources.md
  - Contributing: contributing.md
  - Changelog: changelog.md

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