MkDocs Material 花哨功能巡展

这页把 MkDocs Material 常用的"花哨玩法"集中演示一遍。每一块下面都附了写法， 想用哪个直接抄。

1. 提示框（Admonitions）

有十几种类型，颜色和图标各不相同：

笔记

普通说明用 !!! note。

小技巧

绿色，用 !!! tip。

警告

黄色，用 !!! warning。

危险

红色，用 !!! danger。适合放"别删这个"之类。

成功

也有 success / info / question / bug / example 等。

写法：

!!! tip "标题"
    缩进的内容。

2. 可折叠块（点击展开）

点我展开（默认收起）

用 ??? 代替 !!! 就变可折叠。适合放长内容、答案、细节。

默认展开的可折叠块

???+ 是默认展开、但可收起。

3. 内容标签页（Tab 切换）

PythonJavaScriptRust

print("Hello")

console.log("Hello");

println!("Hello");

写法：用 === "标签名" 起头，内容缩进。多个 Tab 会横向排列。

4. 代码高亮 + 行号 + 一键复制 + 高亮某行

def greet(name):
    msg = f"Hello, {name}!"   # 这行被高亮
    return msg                # 这行也被高亮

• title="..." 给代码块加标题
• linenums="1" 显示行号
• hl_lines="2 3" 高亮第 2、3 行
• 右上角自动有复制按钮

5. 代码注解（气泡说明）

theme:
  name: material  # (1)!

1. 这就是一个代码注解——代码里放 # (1)!，下面用有序列表写说明， 网页上会渲染成一个可点击的圆圈气泡。适合逐行讲解配置。

6. 文字排版小玩法

• 高亮：这段被高亮（==文字==）
• 删除线：这段被删掉（~~文字~~）
• 上标：H²O、10³（^文字^）
• 下标：CO₂（~文字~）
• 键盘按键：按 Ctrl+C 复制、Cmd+Shift+P（++ctrl+c++）

7. 表情与图标

支持 这类 Material 图标， 以及 这类 emoji。

写法：:material-rocket:（图标）、:smile:（emoji）。 图标库很大，可在 Material 官网搜名字。

8. 按钮

普通链接可以变成按钮（用 attr_list）：

点我看搭建记录 主按钮样式

写法：[文字](链接){ .md-button }

9. 流程图（Mermaid）

直接用文字描述，自动画成图：

graph LR
    A[写 .md] -->|git push| B[GitHub]
    B -->|webhook| C[Cloudflare 构建]
    C -->|mkdocs build| D[HTML]
    D --> E[网站上线]

写法：```mermaid 代码块里写 Mermaid 语法。支持流程图、时序图、类图、甘特图等。

10. 数据表格

功能	写法难度	效果
提示框	简单	醒目
标签页	简单	省空间
Mermaid	中等	专业

（:--- 左对齐、:---: 居中、---: 右对齐）

11. 脚注

正文里放个引用¹，页面底部自动生成脚注区。

---

小结

这些全部只靠 Markdown（加几个已在 mkdocs.yml 里开启的扩展）就能写出来， 无需手写 HTML/CSS。想用哪个，回来抄这页的写法即可。

---

1. 这就是脚注内容，写法是 [^1] 引用 + [^1]: 内容 定义。 ↩