MkDocs 与 Material 主题语法使用手册

这是一份面向本 Wiki 的可复制手册，覆盖站点配置、常用 Markdown 扩展和 Material 主题功能。

本仓库当前使用 mkdocs-material 9.6.14。mkdocs.yml 已启用本手册中演示的提示块、可折叠提示块、代码高亮与注释、内容选项卡、脚注、任务列表、按键、Emoji、文本标记、属性列表、搜索、代码复制和顶部标签导航；文中标为“按需启用”的主题功能，仍需要先把对应配置加入 mkdocs.yml。

1. 基础配置：`mkdocs.yml`

mkdocs.yml 位于仓库根目录，是 MkDocs 的主配置文件。YAML 用缩进表示层级，建议统一使用两个空格，不能混用 Tab。

1.1 核心配置项速查

配置项	作用	示例
`site_name`	浏览器标题、站点名称	`Jie's Wiki`
`site_url`	站点公开地址；社交卡片、canonical URL 等功能需要它	`https://wiki.example.com`
`site_description`	页面描述和搜索引擎摘要	`个人知识库`
`site_author`	作者信息	`王永杰`
`docs_dir`	Markdown 文档目录，默认是 `docs`	`docs`
`site_dir`	构建后的静态文件目录，默认是 `site`	`site`
`nav`	手动指定导航顺序和显示名称	`- 首页: index.md`
`theme`	主题、语言、颜色、功能开关	`name: material`
`markdown_extensions`	额外 Markdown 语法能力	`- admonition`
`plugins`	搜索、博客、压缩等构建插件	`- search`
`extra_css` / `extra_javascript`	加载自定义样式和脚本	`- stylesheets/extra.css`
`extra`	主题使用的附加数据，如社交链接、版本提供方	`social: ...`

1.2 一份完整的起步配置

下面的示例包含本文大部分语法所需的扩展。可整体复制后按实际路径、仓库地址和站点名称修改。

site_name: Jie's Wiki
site_url: https://wiki.example.com
site_description: 用于长期沉淀与回顾的个人知识库
site_author: 王永杰

docs_dir: docs
site_dir: site

# 二选一：使用 nav 手动固定导航；若使用 awesome-pages，则可删除 nav，改由 docs/.pages 管理。
nav:
  - 首页: index.md
  - 工具相关:
      - MkDocs 语法使用文档: 工具相关/MkDocs/语法使用文档.md

theme:
  name: material
  language: zh
  font:
    text: Noto Sans SC
    code: JetBrains Mono
  features:
    - navigation.tabs
    - navigation.path
    - navigation.instant
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
  palette:
    # 跟随系统浅色/深色偏好，并提供切换按钮
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

plugins:
  - search

markdown_extensions:
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

extra_css:
  - stylesheets/extra.css
extra_javascript:
  - javascripts/extra.js

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/your-account
      name: GitHub

copyright: Copyright © 2017 - 2026 Your Name

1.3 导航：手动 `nav` 与自动 `.pages`

nav 适合少量、固定的站点；它会完全接管导航，未列出的文档通常不会出现在导航中。

nav:
  - 首页: index.md
  - 开发相关:
      - 前端: 前端相关/index.md
      - 后端: 后端开发/index.md
  - 投稿: submission.md

本 Wiki 已安装 mkdocs-awesome-pages-plugin，更适合目录会持续增长的知识库。保持 mkdocs.yml 中的 - awesome-pages，然后在 docs/.pages 中调整顶级顺序：

nav:
  - index.md
  - 人工智能
  - 前端相关
  - 后端开发
  - ...
  - submission.md

... 表示其余新文件夹或文章自动收纳到该位置；因此新增目录时不必每次修改 mkdocs.yml。

2. Markdown 基础与扩展语法

2.1 标题、链接、图片、列表与表格

标题请从 # 开始，页面通常只保留一个一级标题。##、### 会自动出现在右侧目录中。

渲染结果（详见下方）：标题按层级显示为不同字号；普通链接为主题强调色；表格有横向分隔线，窄屏时可横向滚动。

# 页面标题

## 二级标题

### 三级标题

访问 [MkDocs 官网](https://www.mkdocs.org/)。

![图片替代文字](../../assets/example.png "悬停提示文字")

- 无序列表
  - 二级项目
1. 有序列表
2. 第二项

| 配置 | 说明 |
| --- | --- |
| `site_name` | 站点名称 |
| `theme` | 主题配置 |

实际渲染示例

这是一个可直接点击的 MkDocs 链接。

无序列表第一项
- 无序列表第二层
有序列表第一项
1. 有序列表第二项

配置	说明
`site_name`	站点名称
`theme`	主题配置

2.2 提示块（Admonitions）

需要配置：

markdown_extensions:
  - admonition

渲染结果（详见下方）：正文中出现带左侧图标、浅色背景和标题的提示卡片。note、tip、warning、danger 会使用不同语义色彩。

!!! note "说明"
    这是普通说明，适合补充背景信息。

!!! tip "建议"
    建议在提交前执行 `mkdocs build`。

!!! warning "注意"
    YAML 的缩进不能使用 Tab。

!!! danger "风险"
    部署前请确认目标分支和发布目录。

这是直接渲染的说明

这一段没有放进源码代码块，因此会直接显示为提示卡片。

这是直接渲染的建议

修改配置后，执行 mkdocs build 验证结果。

这是直接渲染的注意事项

YAML 必须使用空格缩进，不能使用 Tab。

常用类型包括 note、abstract、info、tip、success、question、warning、failure、danger、bug、example、quote。标题可以省略；省略后 Material 会显示该类型的默认标题。

2.3 可折叠提示块

需要配置：

markdown_extensions:
  - admonition
  - pymdownx.details

渲染结果（详见下方）：页面初始只显示一行标题和展开箭头；点击后展开内部内容。使用 ???+ 时初始即展开。

??? note "点击查看详细说明"
    这部分内容默认折叠，适合放较长的补充说明。

???+ tip "默认展开的提示块"
    页面加载时这段内容已经展开。

直接渲染：点击展开

这里是默认折叠的内容。点击标题行即可展开或收起。

直接渲染：默认展开

这个提示块使用 ???+，打开页面时内容已经显示。

2.4 代码块、高亮、行号与复制

需要配置：

theme:
  features:
    - content.code.copy

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.superfences

渲染结果（详见下方）：代码块使用等宽字体和语法着色；右上角有复制按钮；标题显示在代码块顶部，指定行会以浅色背景突出。行号可点击并生成链接。

```python title="hello.py" linenums="1" hl_lines="2"
def greet(name: str) -> str:
    return f"Hello, {name}"  # 这一行会高亮

print(greet("Jie"))
```

行内代码直接使用反引号：

使用 `mkdocs build` 生成静态站点。

实际渲染：hello.py
def greet(name: str) -> str:
    return f"Hello, {name}"  # 这一行会高亮

print(greet("Jie"))

这是一段实际渲染的行内代码：mkdocs build。

2.5 代码注释（Annotations）

需要配置：

theme:
  features:
    - content.code.annotate

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.inlinehilite

渲染结果（详见下方）：代码行尾显示圆形数字标记；鼠标悬停或点击数字后，会显示下方对应说明。适合解释配置中容易忽略的行。

```yaml
theme:
  name: material  # (1)!
  language: zh
```

1. `material` 是主题名称；安装 `mkdocs-material` 后即可使用。

实际渲染：主题配置

theme:
  name: material  # (1)!
  language: zh

material 是当前站点使用的主题名称。

2.6 内容选项卡（Content Tabs）

需要配置：

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

渲染结果（详见下方）：同一位置显示一排标签，例如 Python、JavaScript；点击标签后切换对应内容，不会跳转页面。标签标题相同的选项卡可在页面内同步切换。

=== "Python"

    ```python
    print("Hello, MkDocs")
    ```

=== "JavaScript"

    ```javascript
    console.log("Hello, MkDocs")
    ```

PythonJavaScript

print("这是 Python 选项卡")

console.log("这是 JavaScript 选项卡")

注意：标签内容必须比 === 行多缩进四个空格；代码围栏也要随内容一起缩进。

2.7 脚注

需要配置：

markdown_extensions:
  - footnotes

渲染结果（详见下方）：正文中显示可点击的上标编号；页面底部自动生成脚注列表，并带有返回正文的链接。

MkDocs 是静态站点生成器。[^mkdocs]

[^mkdocs]: 它把 Markdown 文档构建为 HTML 静态站点。

下面这句话带有一个实际渲染的脚注。¹

2.8 任务列表

需要配置：

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true

渲染结果（详见下方）：列表项前显示 Material 风格的复选框；已完成项为勾选状态。它用于表达文档状态，不会把 Markdown 文件本身自动改写。

- [x] 完成 `mkdocs.yml` 基础配置
- [x] 编写第一篇文章
- [ ] 检查站内链接
- [ ] 发布到线上

这是一项已完成的任务
这是一项待完成的任务

2.9 定义列表、键盘按键与 Emoji

需要配置：

markdown_extensions:
  - def_list
  - pymdownx.keys
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

渲染结果（详见下方）：定义列表左侧是术语、下方或右侧是解释；键盘按键呈现为圆角按键；Emoji 使用统一 SVG 图标样式。

MkDocs
:   用 Markdown 构建静态文档站点的工具。

Material for MkDocs
:   MkDocs 的一个主题与功能套件。

按 ++ctrl+s++ 保存文件，然后执行 :material-rocket-launch: 构建。

MkDocs: 将 Markdown 文档构建为静态网站的工具。
Material for MkDocs: 提供主题、搜索和丰富扩展能力的 MkDocs 主题。

按 Ctrl+S 保存，然后执行构建。

2.10 上标、下标、删除线与高亮文本

需要配置：

markdown_extensions:
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde

渲染结果（详见下方）：文字可显示为上标、下标、删除线或带背景色的高亮标记。

H~2~O 是水。

2^10^ 等于 1024。

~~过期内容~~

==重点内容==

H₂O 是水；2¹⁰ 等于 1024；~~这一句已过期~~；这是高亮的重点内容。

2.11 HTML 属性：按钮、图片尺寸与锚点

需要配置：

markdown_extensions:
  - attr_list

渲染结果（详见下方）：链接可呈现为主题按钮；图片会按指定宽度显示；标题保留可直接跳转的锚点。

[访问 GitHub](https://github.com/){ .md-button .md-button--primary }
[普通按钮](https://www.mkdocs.org/){ .md-button }

![示例图片](../../assets/example.png){ width="420" }

## 可直接跳转的小节 { #quick-start }

这是直接渲染的主按钮这是直接渲染的普通按钮

可直接跳转的示例小节

上方两个链接已经应用 Material 按钮样式；图片同样可在图片 Markdown 后追加 { width="420" } 控制显示宽度。

3. Material 主题功能与配置

3.1 站内搜索、搜索建议和高亮

需要配置：

plugins:
  - search

theme:
  features:
    - search.suggest
    - search.highlight
    - search.share

渲染结果（详见下方）：顶部搜索图标打开搜索面板；输入关键词后显示标题和正文匹配建议；进入文章后，匹配文本以高亮背景标出。search.share 会在搜索面板中提供复制搜索链接的入口。

search 是 MkDocs 默认可用的插件。若配置了 plugins，需要显式保留它，否则站内搜索不会构建索引。

3.2 代码复制按钮

需要配置：

theme:
  features:
    - content.code.copy

渲染结果（详见下方）：每个代码块右上角出现复制图标；点击后复制代码内容，适合配置和命令示例。代码块语法见 2.4 代码块、高亮、行号与复制。

3.3 深色模式与浅色模式切换

需要配置：

theme:
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

渲染结果（详见下方）：页面顶部显示太阳或月亮图标；首次访问时跟随系统主题，点击图标后可手动切换，Material 会记住用户的选择。

default 是浅色方案，slate 是 Material 内置深色方案。primary 控制主色，accent 控制链接、选中态等强调色。

3.4 顶部标签导航与导航行为

需要配置：

theme:
  features:
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.expand
    - navigation.path
    - navigation.top

渲染结果（详见下方）：一级导航显示在顶部标签栏；滚动后标签栏可固定在顶部；左侧目录按分区展开；文章底部出现“回到顶部”按钮；标题下方展示当前位置面包屑。

这些功能均按需选择。知识库目录较多时，优先使用 navigation.tabs、navigation.path；navigation.expand 会默认展开全部左侧目录，内容很多时可能使侧栏过长。

需要配置：

site_url: https://wiki.example.com

plugins:
  - social:
      cards: true
      cards_layout_options:
        background_color: "#4051b5"
        color: "#ffffff"

渲染结果（详见下方）：将文章链接分享到微信、聊天工具或社交平台时，预览卡片会显示站点名、文章标题和主题背景图，而不是只有一条裸链接。

社交卡片在构建阶段生成，通常会增加构建时间。必须设置可公开访问的 site_url；首次启用前，应在本地构建一次确认运行环境具备图片/字体生成所需依赖。

3.6 社交链接与页脚

需要配置：

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/your-account
      name: GitHub
    - icon: fontawesome/solid/envelope
      link: mailto:hello@example.com
      name: 发送邮件

copyright: Copyright © 2026 Your Name

渲染结果（详见下方）：页脚显示 GitHub、邮箱等圆形图标；鼠标悬停会显示名称，点击会跳转到对应地址。

3.7 标签系统（Tags）

需要配置：

plugins:
  - search
  - tags:
      tags_file: 标签.md

每篇文章在 YAML 中填写标签：

---
title: requests 入门
tags:
  - Python
  - 爬虫
---

标签汇总页 docs/标签.md 的内容：

# 标签

渲染结果（详见下方）：文章标题附近出现可点击的标签；标签页按标签归集所有相关文章。tags 是 Material 自带插件，不需要额外安装包。

3.8 博客功能（Blog）

需要配置：

plugins:
  - search
  - blog:
      blog_dir: 博客
      post_dir: 博客/posts
      post_date_format: full

文章文件示例：

---
date:
  created: 2026-08-01
categories:
  - 随笔
tags:
  - MkDocs
---

# 一篇博客文章

渲染结果（详见下方）：博客首页按时间展示文章卡片；文章可显示创建日期、分类和标签，并能自动产生归档页。blog 同样是 Material 自带插件。

3.9 版本选择器（Mike）

适合需要同时维护多个文档版本的项目，例如 v1.0、v2.0 与 latest。个人 Wiki 通常不需要启用。

先安装工具：

python -m pip install mike

配置版本提供方：

extra:
  version:
    provider: mike

首次发布与后续发布命令：

# 将当前文档发布为 1.0，并创建 latest 别名
mike deploy --push --update-aliases 1.0 latest

# 发布下一版本
mike deploy --push --update-aliases 2.0 latest

# 本地预览已发布版本
mike serve

渲染结果（详见下方）：页面顶部或底部出现当前版本名称；点击后打开版本下拉列表，可切换到 1.0、2.0、latest 等已发布版本。Mike 会使用 Git 分支保存不同版本的静态站点，启用前应确认团队的发布策略。

4. 常用插件推荐

插件写入 mkdocs.yml 的 plugins。配置了 plugins 后，search 必须显式保留。

插件	是否额外安装	用途	最小配置
`search`	否	生成站内全文搜索索引	`- search`
`awesome-pages`	是，本仓库已安装	用 `.pages` 管理自动导航顺序	`- awesome-pages`
`blog`	否，Material 自带	生成博客文章、归档、分类页	`- blog`
`tags`	否，Material 自带	为文章生成标签与标签索引页	`- tags`
`social`	否，Material 自带	构建分享预览图	`- social`
`minify`	是	压缩 HTML，减小静态文件体积	`- minify`
`redirects`	是	为旧链接生成跳转，避免改名后 404	`- redirects`
`git-revision-date-localized`	是	显示 Git 最后修改日期	`- git-revision-date-localized`

外部插件应同时安装到本地与 CI 环境，建议写入 requirements.txt：

mkdocs-material==9.6.14
mkdocs-awesome-pages-plugin==2.9.3
mkdocs-minify-plugin
mkdocs-redirects
mkdocs-git-revision-date-localized-plugin

对应的插件配置示例：

plugins:
  - search
  - awesome-pages
  - minify:
      minify_html: true
  - redirects:
      redirect_maps:
        旧路径.md: 新路径.md
  - git-revision-date-localized:
      enable_creation_date: true
      type: date
      locale: zh

安装或更新依赖后执行：

python -m pip install -r requirements.txt
mkdocs build

5. 本地预览、构建与发布

5.1 本地预览

mkdocs serve

终端会输出本地访问地址。保存 Markdown、YAML 或样式文件后，页面通常自动刷新。

5.2 静态构建检查

mkdocs build
git diff --check

渲染结果（详见下方）：构建成功后，根目录的 site/ 中生成完整静态网站；浏览器看到的就是该目录中的 HTML、CSS、JavaScript 和资源文件。git diff --check 用来检查行尾空格、冲突标记等格式问题。

若希望把构建警告也视为错误，可在无已知警告的项目中使用：

mkdocs build --strict

5.3 使用 `mkdocs gh-deploy` 发布到 GitHub Pages

适用于由 gh-pages 分支直接托管的网站：

# 先确认站点能构建
mkdocs build

# 构建并推送 site 内容到 gh-pages 分支
mkdocs gh-deploy

首次使用前，在 GitHub 仓库 Settings → Pages 中将发布源选择为 gh-pages 分支。该命令会改写 gh-pages 分支的生成文件，因此不要在该分支手工维护业务源码。

5.4 本仓库的 GitHub Actions 发布方式

本 Wiki 已使用 .github/workflows/deploy.yml 自动部署。它会在 wiki 分支推送、且提交信息含 #部署 时构建并发布。因此当前仓库通常不需要执行 mkdocs gh-deploy：

git add mkdocs.yml docs overrides requirements.txt
git commit -m "docs: 更新 MkDocs 手册 #部署"
git push origin wiki

推送后在 GitHub 仓库的 Actions 页面查看流水线结果。发布前仍建议先本地运行 mkdocs build。

6. 新建文章最小模板

复制下面模板新建文章，可保持当前 Wiki 的评论行为一致：

---
title: 文章标题
comments: true
tags:
  - 示例标签
---

# 文章标题

一句话说明本文要解决的问题。

## 背景

## 操作步骤

## 注意事项

## 参考资料

写完后执行 mkdocs build，确认文章能进入导航、代码块和链接均正常显示。

脚注会在本页底部自动集中显示，并可跳回引用位置。 ↩

MkDocs 与 Material 主题语法使用手册

1. 基础配置：mkdocs.yml

1.1 核心配置项速查

1.2 一份完整的起步配置

1.3 导航：手动 nav 与自动 .pages

2. Markdown 基础与扩展语法

2.1 标题、链接、图片、列表与表格

实际渲染示例

2.2 提示块（Admonitions）

2.3 可折叠提示块

2.4 代码块、高亮、行号与复制

2.5 代码注释（Annotations）

2.6 内容选项卡（Content Tabs）

2.7 脚注

2.8 任务列表

2.9 定义列表、键盘按键与 Emoji

2.10 上标、下标、删除线与高亮文本

2.11 HTML 属性：按钮、图片尺寸与锚点

可直接跳转的示例小节

3. Material 主题功能与配置

3.1 站内搜索、搜索建议和高亮

3.2 代码复制按钮

3.3 深色模式与浅色模式切换

3.4 顶部标签导航与导航行为

3.5 社交卡片（Open Graph Social Cards）

3.6 社交链接与页脚

3.7 标签系统（Tags）

3.8 博客功能（Blog）

3.9 版本选择器（Mike）

4. 常用插件推荐

5. 本地预览、构建与发布

5.1 本地预览

5.2 静态构建检查

5.3 使用 mkdocs gh-deploy 发布到 GitHub Pages

5.4 本仓库的 GitHub Actions 发布方式

6. 新建文章最小模板

评论

1. 基础配置：`mkdocs.yml`

1.3 导航：手动 `nav` 与自动 `.pages`

5.3 使用 `mkdocs gh-deploy` 发布到 GitHub Pages