⚡

MkDocs-Material文档构建技能Skill mkdocs-material

MkDocs-Material文档构建技能是专门用于配置和优化基于Python的文档系统的专业技能。该技能专注于使用Material主题的MkDocs框架，提供完整的文档站点搭建解决方案，包括导航配置、插件集成、多语言支持、PDF导出、版本控制等功能。适用于技术文档、API文档、产品手册等各类文档项目的快速部署和高效管理。关键词：MkDocs文档构建，Material主题配置，Python文档系统，技术文档自动化，多语言文档支持，版本控制部署，静态站点生成，开发者文档工具。

DevOps 0 次安装 0 次浏览 更新于 2/26/2026

name: mkdocs-material description: 专注于Python文档的MkDocs与Material主题专业技能。配置导航、插件、多语言支持、PDF导出及高级Material主题功能。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep backlog-id: SK-003 metadata: author: babysitter-sdk version: “1.0.0”

MkDocs/Material 技能

专注于Python文档的MkDocs与Material主题专业技能。

能力

  • 使用Material主题功能配置mkdocs.yml
  • 设置导航和目录
  • 启用和配置MkDocs插件（搜索、宏、Mermaid）
  • 使用提示框和代码注释
  • 配置多语言支持
  • 生成PDF导出配置
  • 集成GitHub Pages部署
  • 启用博客和版本控制功能

使用方法

在以下情况时调用此技能：

  • 使用Material主题设置MkDocs
  • 配置高级主题功能
  • 添加插件以扩展功能
  • 设置多语言文档
  • 使用mike启用版本控制

输入参数

参数 类型 必填 描述
action string 是 init, configure, plugin, deploy
projectPath string 是 MkDocs项目路径
config object 否 配置选项
plugins array 否 要配置的插件
locale string 否 语言区域设置

输入示例

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

项目配置

mkdocs.yml

site_name: 我的文档
site_url: https://docs.example.com
site_description: 我的产品开发者文档
site_author: 我的团队

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: 切换到深色模式
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式
  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同意
    description: 我们使用Cookie来改善您的体验。

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js

nav:
  - 首页: index.md
  - 快速开始:
    - 安装: getting-started/installation.md
    - 快速入门: getting-started/quick-start.md
    - 配置: getting-started/configuration.md
  - 用户指南:
    - user-guide/index.md
    - 认证: user-guide/authentication.md
    - API使用: user-guide/api-usage.md
  - API参考:
    - api/index.md
    - 客户端: api/client.md
    - 资源: api/resources.md
  - 贡献指南: contributing.md
  - 更新日志: changelog.md

提示框

标准提示框

!!! note "自定义标题"
    这是一个带有自定义标题的注释。

!!! tip
    这是一个有用的提示。

!!! warning
    这是一个警告信息。

!!! danger "关键"
    这是一个关键危险信息。

!!! info
    这是一个信息说明。

!!! success
    这表示成功。

!!! question
    这提出了一个问题。

!!! quote
    这是一个引用。

??? example "可折叠示例"
    此内容可折叠（默认关闭）。

???+ example "可折叠示例（打开）"
    此内容可折叠（默认打开）。

代码注释

带注释的代码块

```python
import requests

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

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

1. 导入requests库进行HTTP调用
2. 在请求头中包含认证令牌
3. 解析JSON响应

内容标签页

标签页内容

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

使用Mike进行版本控制

mike配置

# 部署版本
mike deploy --push --update-aliases 1.0 latest

# 设置默认版本
mike set-default --push latest

# 列出版本
mike list

# 删除版本
mike delete 0.9

版本化文档结构

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

多语言支持（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导出

pdf-export插件

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

Mermaid图表

Mermaid集成

```mermaid
sequenceDiagram
    participant U as 用户
    participant A as API
    participant D as 数据库

    U->>A: 请求
    A->>D: 查询
    D-->>A: 结果
    A-->>U: 响应
```

宏插件

自定义宏

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

<!-- 在文档中使用 -->
当前版本: {{ version() }}

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

工作流程

  1. 初始化项目 - 创建MkDocs项目结构
  2. 配置主题 - 设置Material主题
  3. 添加插件 - 启用所需插件
  4. 结构导航 - 在mkdocs.yml中配置导航
  5. 添加内容 - 编写Markdown文档
  6. 构建 - 生成静态站点
  7. 部署 - 发布到托管平台

依赖项

# 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命令

# 创建新项目
mkdocs new my-docs

# 启动开发服务器
mkdocs serve

# 构建静态站点
mkdocs build

# 部署到GitHub Pages
mkdocs gh-deploy

# 使用mike部署版本化文档
mike deploy --push --update-aliases 1.0 latest

最佳实践

  • 为顶级部分使用导航标签页
  • 启用即时加载以获得SPA体验
  • 配置搜索建议
  • 添加代码复制按钮
  • 使用提示框进行标注
  • 启用深色/浅色模式切换
  • 在页脚添加社交链接

参考

目标流程

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