能力展示 · 文档中心写作指南（MarkDown Demo）¶

📄 创建: 段晋明 2026-08-02

https://doc.xpku.com/raw/tools/markdown-demo.md

这页演示文档中心（MkDocs Material）支持的全部能力。既是给人看的样式册，也是给所有 Agent 的写作参考——照着写，就能产出图文并茂、结构清晰的文档。

页面右上角 可切换 暗 / 亮 主题；左侧导航可展开折叠；顶部支持全文搜索。

1. 文字强调¶

粗体 · 斜体 · 高亮 · 删除线 · 下划线

键盘按键：Ctrl+C · Ctrl+Shift+N · Enter

**粗体** · *斜体* · ==高亮== · ~~删除线~~ · ^^下划线^^
++ctrl+c++ · ++enter++

2. Emoji 与图标¶

表情：

Material 图标：

:smile: :rocket: :white_check_mark:
:material-lightbulb: :material-check-circle:

图标全集见 https://pictogrammers.com/library/mdi/ ，写法 :material-图标名:

3. 任务列表¶

• 环境搭建
• 配置拉满
• 接入 Git hooks
• 上线合规检查

4. 提示框 Admonition¶

普通说明。

摘要 / 总结。

一般提示。

实用建议，鼓励采用。

最佳实践 / 操作成功。

FAQ。

需要注意，可能出错。

反模式 / 失败案例。

严重警告，禁止行为。

已知问题。

演示 / 示例。

引用他人内容。

可折叠提示框¶

适合放长内容、补充说明、日志片段，默认不占空间。

带 + 默认展开，用户可手动折叠。

!!! tip "标题"
    内容缩进 4 空格

??? warning "默认收起"
    点标题展开

???+ note "默认展开"
    带 + 号

5. 代码块¶

带行号 + 复制按钮 + 指定行高亮：

def greet(name):
    message = f"Hello, {name}!"
    return message

代码标注 Annotations¶

def deploy():  # (1)!
    build()    # (2)!
    ship()

1. 部署入口函数
2. 先构建产物再发布

行内代码 variable、def f(): 也支持高亮。

6. 内容标签页 Tabs¶

前端规范：组件化、响应式、TypeScript。

后端规范：分层架构、RESTful、统一异常处理。

数据库规范：命名、索引、迁移脚本。

开启了 content.tabs.link，多组 Tabs 会同步切换——在一处切到「后端」，全文后端 tab 跟着切。

=== "前端"
    前端内容（缩进 4 空格）

=== "后端"
    后端内容

7. Mermaid 图表¶

流程图 flowchart¶

分支图 gitGraph¶

时序图 sequence¶

类型：flowchart / gitGraph / sequenceDiagram / classDiagram / stateDiagram

8. 表格¶

9. 脚注与缩写¶

文档中心基于 MkDocs¹，主题用 Material for MkDocs²。鼠标悬停下面缩写看释义：用 W3C 标准。

10. 图片（操作手册 / 截图）¶

支持 PNG / JPG / SVG / GIF。图片放进 docs/ 下任意目录，相对路径引用，可控制 width / align：

![登录界面](assets/login.png){ width="400" }
![错误提示](assets/error.png){ align=right }

✍️ 给 Agent 的写作建议¶

1. 警告 / 建议用提示框，别用裸文字——!!! warning / !!! tip 更醒目。
2. 流程、分支、时序画成 Mermaid 图，别用 A->B->C 文字箭头。
3. 同类内容（前 / 后端 / DB）放 Tabs，减少滚动。
4. 代码块必加语言（```py / ```js / ```sql），才有高亮、行号、一键复制。
5. 操作手册每步配截图，图片放 assets/，![描述](assets/xxx.png) 引用。
6. 长补充内容用 ??? 折叠，保持主流程清爽。
7. 关键概念 ==高亮==，反例 ~~~删除线~~~ + !!! danger。

本页由 墨 整理维护。新增能力需求或发现遗漏，发消息给墨。