MkDocs & Material for MkDocs 速查

格式说明：每部分先用一句话说明，接着（如需）给出常见的 mkdocs.yml 配置片段，然后在代码块内列出所有常见用法示例，最后说明该语法/配置的效果。

简介

Material for MkDocs 是基于 MkDocs 的现代文档主题，提供许多扩展与短语法来美化文档和加入交互功能。

基本操作指令

常用的本地开发与构建命令。

pip install mkdocs           # 只用mkdocs
pip install mkdocs-material  # 直接安装mkdocs-material，包含mkdocs
mkdocs new mkd               # 新建项目，文件夹命名为mkd
mkdocs serve                 # 本地实时预览，用于开发测试
mkdocs build                 # 生成静态网站到 site/
mkdocs build --clean         # 删除旧site文件夹再生成
mkdocs gh-deploy             # 一键部署到 GitHub Pages（需安装插件）

程序块（代码高亮）

使用围栏代码块并声明语言以获得语法高亮、行号、标题、复制按钮等。

基础用法

行内代码块

内嵌 `print("这是行内代码块")` 在文字里面。

内嵌有高亮的 `#!python print("这是行内代码块")` 在文字里面。

效果：

内嵌 print("这是行内代码块") 在文字里面。

内嵌有高亮的 print("这是行内代码块") 在文字里面。

独立代码块

```python
print("Hello world")
```

print("Hello world")

显示行号

```python linenums="1"
for i in range(5):
    print(i)
    print(i+1)
```

for i in range(5):
    print(i)
    print(i+1)

高亮某几行

```python hl_lines="1-2"
print("这行高亮")
print("这行也高亮")
print("这行没高亮")
```

print("这行高亮")
print("这行也高亮")
print("这行没高亮")

标题

```python title="example.py"
print("来自 example.py")
```

print("来自 example.py")

提示框（Admonitions）

用 !!! 类型 创建信息/警告/提示等块级提示。

!!! note "小提示"
    这是一个注意提示，支持 **Markdown**。
    ```python
    print("提示框内也可以有代码块")
    ```
    “复制”的快捷键是++ctrl+c++。

!!! warning
    小心：这是一条警告。

??? tip "点开看看"
    用 `???` 可以默认折叠提示框。

小提示

这是一个注意提示，支持 Markdown。

print("提示框内也可以有代码块")

“复制”的快捷键是Ctrl+C。

Warning

小心：这是一条警告。

点开看看

用 ??? 可以默认折叠提示框。

文字格式化

Material 支持常见 markdown 与额外扩展（例如高亮、下标、上标）。

启用 pymdownx 扩展：

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

用法：

*斜体* / **粗体** / `行内代码`

==高亮== / H~2~O / X^2^

新增 / 删除 / 替换新文本

键位： ++ctrl+c++ / ++win+alt+del++

注意：++ 前后不能有空格。

效果：

斜体 / 粗体 / 行内代码

高亮 / H₂O / X²

新增 / 删除 / 替换新文本

键位： Ctrl+C / Win+Alt+Del

参考

• Formatting - Material for MkDocs
• PyMdown Extensions Documentation

多标签页（Tabs）

用 === '标签名' 创建页面内的选项卡（多标签页）。

单组标签：

=== "Python"
    ```python
    print("这是 python 程序")
    ```

=== "C++"
    ```cpp
    cout << "这是C++程序" << endl;
    ```

嵌套或多组标签：

=== "输出"
    === "Python"
      ```python
      print("这是 python 输出")
      ```

    === "C++"
      ```cpp
      cout << "这是 C++ 输出" << endl;
      ```

=== "输入"
    === "Python"
      ```python
      a = input("这是 python 输入")
      ```

    === "C++"
      ```cpp
      cin >> a;
      ```

单组标签：

PythonC++

print("这是 python 程序")

cout << "这是C++程序" << endl;

嵌套或多组标签：

输出输入

Python

print("这是 python 输出")

C++

cout << "这是 C++ 输出" << endl;

Python

a = input("这是 python 输入")

C++

cin >> a;

指定默认标签

=== "标签 1"
    标签 1 的内容。

===+ "标签 2"
    标签 2 的内容。

=== "标签 3"
    标签 3 的内容。

标签 1标签 2标签 3

标签 1 的内容。

标签 2 的内容。

标签 3 的内容。

图表

可直接嵌入 Mermaid（流程图/时序图/类图）或使用其他图表插件实现交互图表。

启用 Mermaid：

markdown_extensions:
  - pymdownx.superfences
extra_javascript:
  - https://unpkg.com/mermaid@10/dist/mermaid.min.js

流程图（Mermaid）

```mermaid
graph TD
    A[开始] --> B{条件判断}
    B -- 是 --> C[执行动作]
    B -- 否 --> D[结束]
    C --> D
```

graph TD
    A[开始] --> B{条件判断}
    B -- 是 --> C[执行动作]
    B -- 否 --> D[结束]
    C --> D

序列图（Sequence）

```mermaid
sequenceDiagram
    participant A as 用户
    participant B as 服务器
    A->>B: 发送请求
    B-->>A: 回应结果
```

sequenceDiagram
    participant A as 用户
    participant B as 服务器
    A->>B: 发送请求
    B-->>A: 回应结果

甘特图（Gantt）

```mermaid
gantt
    title 项目时间表
    dateFormat  YY-MM-DD
    section 设计阶段
    设计UI        :done, des1, 24-02-01, 24-02-04
    开发API       :done, dev1, 24-02-05, 24-02-10
    项目测试      :done, test1, 24-02-11, 24-02-14
    section 部署阶段
    部署上线      :done, deploy, 24-02-15, 24-02-16
    用户培训      :active, train, 24-02-17, 24-02-19
    项目回顾      :        retro, 24-02-20, 24-02-23
```

gantt
    title 项目时间表
    dateFormat  YY-MM-DD
    section 设计阶段
    设计UI        :done, des1, 24-02-01, 24-02-04
    开发API       :done, dev1, 24-02-05, 24-02-10
    项目测试      :done, test1, 24-02-11, 24-02-14
    section 部署阶段
    部署上线      :done, deploy, 24-02-15, 24-02-16
    用户培训      :active, train, 24-02-17, 24-02-19
    项目回顾      :        retro, 24-02-20, 24-02-23

饼图（Pie）

```mermaid
pie
    title 桌面端浏览器市占比
    "Google Chrome" : 70.25
    "Microsoft Edge" : 11.80
    "Apple Safari" : 6.34
    "Mozilla Firefox" : 4.94
    "其他" : 6.67
```

pie
    title 桌面端浏览器市占比
    "Google Chrome" : 70.25
    "Microsoft Edge" : 11.80
    "Apple Safari" : 6.34
    "Mozilla Firefox" : 4.94
    "其他" : 6.67

注意：Mermaid 饼图不支持自动计算剩余扇区，需手动给出所有数值（例如先计算总和，再补上“其他”部分）。

Git 分支图（gitGraph）

```mermaid
gitGraph
    commit
    commit
    branch new
    checkout new
    commit
    checkout main
    merge new
    commit
```

gitGraph
    commit
    commit
    branch new
    checkout new
    commit
    checkout main
    merge new
    commit

参考

• Mermaid Tutorial

图标（Icons）

用内置图标短码在文本、标题、按钮中插入图标，或使用 HTML 的图标类。

设置网站标志

theme:
  name: materia
  logo: assets/images/logo.jpg      # 网站左上角logo
  favicon: assets/images/logo.jpg   # 网页标签小图标，16*16/32*32
```### 设置某页在导航栏的标志

如本md文件的最前面加入了：

```markdown
---
icon: material/library
---

你可以在左边导航栏的本文标题前看到一个书本图标（）。

全局设置页尾图标（一般用于社交账号链接）

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/your-repo
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/your-profile
    - icon: material/email
      link: mailto:your@email.com

文本中插入图标

在文本中插入 :simple-counterstrike: 和 :fontawesome-solid-star:

HTML 方式也可以：
<span class="md-icon">:simple-counterstrike:</span>

效果：

在文本中插入 和

HTML 方式也可以：

参考

• Icons, Emojis - Material for Mkdocs（这里可以查内置符号的代码）

设置颜色

通过 theme.palette 或自定义 CSS 设定主色与强调色。

基本设置（主题色）

theme:
  name: material
  palette:
    scheme: default  # 主体模式（如 "default", "slate"）
    primary: blue grey  # 主色
    accent: light blue  # 强调色（按钮、选中项目等）

深色模式

以下是本站的深浅色切换方案。

theme:
  name: material
  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/weather-night
        name: 切换到暗黑模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-sunny
        name: 切换到明亮模式
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: blue grey
      accent: light blue
      toggle:
        icon: material/auto-mode
        name: 切换到系统默认模式

参考色表

MkDocs Material 支持在 primary 和 accent 使用以下颜色：

颜色名	示例
red	🔴
pink	🌸
purple	🟣
deep-purple	🟪
indigo	🔵
blue	🟦
light-blue	🔷
cyan	🌊
teal	🦚
green	🟢
light-green	🍏
lime	🟡
yellow	🟨
amber	🟠
orange	🧡
deep-orange	🟧
brown	🟤
grey	⚪
blue-grey	🌫

设置字体

在 theme.fonts 或通过 extra_css 引入自定义字体并配置回退。

直接使用内置字体

theme:
  font:
    text: 'Roboto'     # 正文字体
    code: 'Fira Code'  # 代码字体

自定义字体

准备一份自己的字体文件（.woff2 最佳 / .ttf），放入docs/assets/fonts/。

新建 stylesheets/fonts.css 如下：

/* 定义自定义字体 */
@font-face {
  font-family: 'MapleMono';
  src: url('../assets/fonts/MapleMonoNormal-Regular.ttf.woff2') format('woff2');
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

/* 此处仅应用代码字体 */
code, pre, .codehilite {
  font-family: 'MapleMono', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif !important;
  font-size: 0.95em;
  line-height: 1.4;
}

然后在 mkdocs.yml 中启用：

extra_css:
  - stylesheets/fonts.css

参考

• Changing the fonts - Material for MkDocs## 设置页脚 在 theme.extra 或 extra 中添加页脚内容或自定义模板。

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/you
  footer: |
    © 2025 公司名称 — 保留所有权利

页脚会自动使用 extra.footer 渲染，或者你可以在主题模板中引用它，在每页底部显示公司信息、社交链接与版权声明。

设定数学式

启用 KaTeX 或 MathJax 并配置渲染分隔符以支持 LaTeX 数学公式。

新建 docs/javascripts/mathjax.js 如下：

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => { 
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

然后启用：

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

用法：

行内： $e^{i\pi} + 1 = 0$

块级：

$$
\int_0^1 x^2 dx = \frac{1}{3}
$$

效果：

行内： \(e^{i\pi} + 1 = 0\)

块级：

\[ \int_0^1 x^2 dx = \frac{1}{3} \]

内嵌网页（iframe）

用 HTML 的 <iframe> 或第三方插件内嵌外部页面/Demo，若需要跨域/安全控制请额外配置服务器/headers。

用法：

<iframe src="../../../assets/html/iframe-demo.html" width="100%" height="500" loading="lazy"></iframe>

加入 .ipynb（Jupyter Notebook）

使用社区插件（如 mknotebooks、mkdocs-jupyter 或 mkdocs-jupyterlite）将 .ipynb 纳入导航并渲染为页面。

plugins:
  - mknotebooks
# 或者
  - mkdocs-jupyter

用法：

# 直接把 notebooks 放到 docs/ 并在 nav 中引用
nav:
  - Notebooks:
    - 介绍: notebooks/intro.ipynb

效果：把 notebook 作为页面渲染，支持包含输出与图片；部分插件可在构建时执行 notebook 并控制输入/输出的显示。

社交卡片设置（Social）

使用内置 social 插件自动生成社交分享图，支持通过 front-matter 或 meta 插件覆盖每页设置。

plugins:
  - social

用法（页面 front-matter 覆盖示例）：

---
title: 我的文章
social:
  image: assets/cards/custom.png
  description: 自定义描述
---

效果：生成可在社交媒体/预览中显示的图像（或自定义布局），提高分享时的可见性。

博客设置

Material 提供内建的博客支持（posts、作者、分类、分页等），并自动生成 RSS 元数据（如启用）。

启用 blog 及 rss 插件：

plugins:
  - blog
  - rss:
      categories:
        - categories
        - tags

用法：

# 在 docs/blog/ 中加入带 front-matter 的 Markdown 文章
---
title: 我的博文
date: 2025-09-30
author: 张三
categories: [更新]
---
内容...

效果：自动生成文章列表、作者页、分类与 RSS 提要，支持分页与评论锚点配置。

RSS 设置

启用 RSS 插件并配置分类或注释路径即可自动生成可发现的 RSS feed。

plugins:
  - rss:
      categories:
        - categories
        - tags
      comments_path: "#__comments"

用法：使用文章 front-matter 填写 metadata 即可。

效果：为站点生成 RSS feed，供订阅器发现文章更新。

参考

• mkdocs官网文档
• Material for Mkdocs官网