Agent skill

mkdocs-material

MkDocs with Material theme expertise for Python-centric documentation. Configure navigation, plugins, multi-language support, PDF export, and advanced Material theme features.

View SKILL.md on GitHub Repository

Stars 514

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/technical-documentation/skills/mkdocs-material

Metadata

Additional technical details for this skill

author: babysitter-sdk
version: 1.0.0

SKILL.md

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

json

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

Project Configuration

mkdocs.yml

yaml

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

markdown

!!! 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

markdown

```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

markdown

=== "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

bash

# 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

yaml

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

Multi-language (i18n)

mkdocs.yml i18n

yaml

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

yaml

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

Mermaid Diagrams

Mermaid Integration

markdown

```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

yaml

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

python

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

markdown

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

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

Workflow

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

Dependencies

text

# 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

bash

# 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

Maintainer

a5c-ai Core maintainer

Source details

Full Name: a5c-ai/babysitter
Branch: main
Path in repo: library/specializations/technical-documentation/skills/mkdocs-material
License: MIT License
Topics: claude-code agent-skills claude-code-skills ai-agents claude-skills vibe-coding agentic-workflow agentic-ai ai-automation agent-orchestration babysitter trustworthy-ai

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

a5c-ai/babysitter

gsd-tools

Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).

514 31

Explore

a5c-ai/babysitter

model-profile-resolution

Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.

514 31

Explore

a5c-ai/babysitter

verification-suite

Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.

514 31

Explore

a5c-ai/babysitter

state-management

STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.

514 31

Explore

a5c-ai/babysitter

git-integration

Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.

514 31

Explore

a5c-ai/babysitter

frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

514 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

Metadata

SKILL.md

MkDocs/Material Skill

Capabilities

Usage

Inputs

Input Example

Project Configuration

mkdocs.yml

Admonitions

Standard Admonitions

Code Annotations

Annotated Code Blocks

Content Tabs

Tabbed Content

Versioning with Mike

mike Configuration

Versioned Docs Structure

Multi-language (i18n)

mkdocs.yml i18n

PDF Export

pdf-export Plugin

Mermaid Diagrams

Mermaid Integration

Macros Plugin

Custom Macros

Workflow

Dependencies

CLI Commands

Best Practices Applied

References

Target Processes

Recommended Agent Skills

gsd-tools

model-profile-resolution

verification-suite

state-management

git-integration

frontmatter-parsing