Markdown 写作规范 v1.1
Markdown 写作规范 v1.1
v1.1 版本要点（2026-05-05）
- 新增 §18 色彩系统 · 3+1 规范（主色玫瑰金 / 辅色曦紫 / 点缀极光青 / 背景夜蓝）
- Admonition 八色 → 统一极光青，视觉不再花乱
- Mermaid 图引入 L0-L5 层级 classDef 预设（作者直接
class X xyL3即可） - C 代码高亮配色重写，解决"夜蓝底上函数名看不见"问题
- 代码块去除 Material 默认双层外框，只保留
.highlight一层
本规范的地位
- 本文是
AlgoDepartment/06_docs所有.md文件的唯一权威写作契约 - 只要每篇文档严格遵守本规范，MkDocs-Material 构建即可保证输出豪华 HTML 的一致性
- 违反本规范的文档 不保证渲染效果，PR 会被打回修正
1. 总则（Do & Don't）
| ✅ 必须 | ❌ 禁止 |
|---|---|
| 每篇文档必须有 frontmatter | 使用 ASCII 框图（╔═╗ ┌─┐）表达架构 |
| H1 只用一次（或交给 frontmatter.title） | 标题跳级（H2 → H4） |
| 用 Mermaid 画流程 / 架构图 | 把架构图做成截图后贴 png |
| 用 Admonition 表达提示/警告 | 用 > ⚠️ 警告：... 这种 emoji-引用 hack |
| 表格保持简洁单元格 | 表格单元内使用 <br> 或嵌 HTML |
产品名写规范拼写（XiStudio） |
写成 xistudio / Xi Studio / XIstudio |
2. Frontmatter（YAML · 必填）
每篇 .md 顶部必须有 YAML frontmatter。字段分为必填、Hero 专用、可选三类。
2.1 必填字段
---
title: 文档标题（与 H1 一致或替代 H1）
description: 一句话说明，用于 <meta description> 与搜索摘要
level: l1a | l1b | l2 | l3 # 决定 Hero 形态与 body class
category: spec | product | arch | api | ops | brand | archive
status: draft | review | published | deprecated
author: 作者或团队（AlgoDepartment / 产品部 / 你的名字）
date: YYYY-MM-DD # 最近一次实质更新日期
---
2.2 Hero 专用字段（仅当 level: l1a 或 l1b 时使用）
hero_show: true # 必须显式开启
hero_label: Documentation · v1.0 # 顶部小标签
hero_title: 主标题 # 不填则用 title
hero_sub: 副标题一句话
hero_meta: "作者：XX · 日期：XX · 版本：XX"
hero_tagline: From Silicon to Sound
hero_stats: # 仅 l1a 推荐使用
- num: "6"
label: 产品层级
- num: "13"
label: 产品线
2.3 可选字段
version: v1.0 # 文档自身版本号
product: XiStudio # 关联的产品线
layer: L4 # 关联的产品层级（L0~L5）
tags: [dsp, mixer, api] # 标签（未来接入搜索过滤）
frontmatter 三个最易错的点
---必须独占一行，不能前后有空格level必须是小写：l1a / l1b / l2 / l3，写L1A不会生效hero_show: true不写就不渲染 Hero，哪怕其它 hero_* 都填了也无效
3. 文档分级（Level 体系）
| Level | 场景 | Hero 形态 | 典型文档 |
|---|---|---|---|
| L1A | 站点首页 / 大板块首页 | 星空 + 三色涟漪 + 统计数字 | index.md 根首页 |
| L1B | 主题级重磅文档 | 简洁渐变 Hero | 产品矩阵、白皮书、规范 |
| L2 | 章节级长文 | 无 Hero，标题带品牌加粗线 | 单个产品 Datasheet、架构分章 |
| L3 | 条目级、备忘、术语表 | 纯内容 | 术语表、FAQ 单条、commit 记录 |
选级原则：不确定就选 L2。L1A/L1B 的 Hero 有视觉重量，不应泛滥。
4. 标题规范
规则：
- 标题之间必须连续递进，禁止跳级（## → ####）
- H2/H3 推荐加编号（## 1. XXX），便于 TOC 显示和交叉引用
- 标题内不使用 emoji（Hero label 和 admonition 可用）
- 同一篇内标题文本唯一，避免 TOC 锚点冲突
5. Admonition（提示框）· 唯一合法的"突出块"
只使用以下 8 种，不允许自创关键字：
!!! note "注记"
普通笔记，中性色
!!! info "信息"
用于补充背景知识
!!! tip "最佳实践"
推荐做法、经验之谈
!!! success "验收通过"
表示某项检查/测试已通过
!!! warning "注意事项"
有风险但可继续，黄色警戒
!!! danger "严重警告"
红色级别，禁止忽略
!!! example "示例"
代码/案例/步骤演练
!!! abstract "摘要"
用于开头的文档纲要
可折叠版本（长内容）：
禁止：
- ❌ 用 > ⚠️ 警告：... 引用块伪造
- ❌ 用 **注意：** 加粗伪造
- ❌ 使用未在上表列出的关键字（如 hint / notice / caution）
6. 列表
6.1 无序列表 · 统一用 -
6.2 有序列表 · 统一用 1. 开头
6.3 任务清单
7. 表格
7.1 基本规则
- 单元格不换行（需要换行请改用列表或拆行）
- 单元格不嵌 HTML 标签（
<br>/<img>/<span>均禁止） - 对齐标记统一（
|:---|:---:|---:|左/中/右） - 表头必须写，且一句话概括
| 英文名 | 中文名 | 层级 | 定位 |
|:------|:------|:----:|:-----|
| XiStudio | 羲音工坊 | L4 | 可视化 IDE 平台 |
| XiDSP | 羲音芯 | L0 | 音频专用 DSP 芯片 |
7.2 复杂信息的替代方案
需要合并单元格、多行描述时，改用 定义列表 或 卡片网格：
XiStudio
: 羲音工坊 · L4 开发工具层
: 可视化音频算法 IDE，提供流图编辑、AI 辅助、编译烧录
XiDSP
: 羲音芯 · L0 芯片基础层
: 车规级音频 DSP，内置 XiCore 运行时
8. 代码块
8.1 必须带语言标签
支持的语言标签（常用）：python / c / cpp / csharp / typescript / javascript / bash / powershell / bat / yaml / json / toml / ini / markdown / mermaid / diff / sql
8.2 行号 & 高亮（Material 扩展）
```python hl_lines="2 4" linenums="1"
def mix(a, b): # 这一行会被高亮
total = a + b
return total # 这一行会被高亮
```
8.3 行内代码
- 变量名 / 文件名 / 命令：
`XiDSP.D2`/`mkdocs.yml` - 键盘按键：
++ctrl+shift+p++→ 渲染为 ⌃⇧P
9. Mermaid 架构图（唯一合法的"图"）
9.1 规范
- 禁止使用 ASCII 框图（
╔═╗、┌─┐） - 禁止把架构图做成截图 后当 png 贴
- 必须用 Mermaid 写成代码块，渲染为 SVG（可搜索、可无障碍、可主题色）
9.2 配色总则（v1.1 · 强制 L0-L5 层级色）
一张流程图只服从"产品层级色 + 语义分支色"两条规则，禁止手写 hex 色值。
所有节点必须显式挂上 xyL0 ~ xyL5（表示所属产品层）或 xySuccess / xyWarn / xyError / xyEnd（表示流程语义）之一；这 10 个 class 已由 xiyin-mermaid.js 预置，无需作者写 classDef。
核心原则：
- 整图主色单一：一张图的节点只在一到两个相邻层级的色系内，避免同时出现 L0 青 + L4 紫 + L5 深紫 等高对比色堆叠导致眼花
- 同层模块同色：如一张图里 XiAmp 与 XiBox 都属 L1，就都用
xyL1（极光青），不再各自找色 - 语义色仅点缀：
xySuccess / xyError这类语义色只用于少数关键节点（终态 / 分支出口），不用来装饰普通中间节点 - 跨层信息流：节点间的连线统一为曦紫
#9D4EDD（由主题的lineColor全局设定，代表"贯穿层级的信息流"），作者无需也不应自定义线色 - 判断菱形：判断节点统一用
xyWarn（玫瑰金#D4A574），让读者一眼识别"这里会分岔"
9.2.1 模板 A · 六层产品矩阵（graph TB）
适用于：产品全景图、架构总览。每层一个颜色，层内模块用同色同类。
```mermaid
graph TB
subgraph L5_["L5 · 云端"]
XiMind[XiMind 云端智脑]
end
subgraph L4_["L4 · 工具"]
XiStudio[XiStudio IDE]
XiForge[XiForge 编译器]
end
subgraph L3_["L3 · 算法"]
XiAlgo[XiAlgo 核心]
end
subgraph L2_["L2 · 测试调音"]
XiTune[XiTune]
XiTest[XiTest]
end
subgraph L1_["L1 · 硬件"]
XiAmp[XiAmp Pro-12]
XiBox[XiBox]
end
subgraph L0_["L0 · 芯片"]
XiDSP[XiDSP-D2]
XiCore[XiCore RT]
end
XiMind --> XiStudio
XiStudio --> XiForge --> XiAlgo
XiAlgo --> XiTune --> XiAmp
XiAmp --> XiDSP
XiDSP --> XiCore
class XiMind xyL5
class XiStudio,XiForge xyL4
class XiAlgo xyL3
class XiTune,XiTest xyL2
class XiAmp,XiBox xyL1
class XiDSP,XiCore xyL0
```
作者写法：只要在图末
class Node1,Node2 xyLn批量打 class 即可。subgraph的背景自动沿用主题的clusterBkg夜蓝，不需要额外着色。
9.2.2 模板 B · 流程图（带判断分支）
适用于：工作流、决策流程。主干走单一层级色，判断节点用 xyWarn，终态用 xySuccess / xyError。
```mermaid
graph LR
Start([开始]) --> Build[XiStudio 导出工程]
Build --> Check{参数合规?}
Check -- 是 --> Compile[XiForge 编译]
Check -- 否 --> Fix[回工坊修正]
Compile --> Flash[烧录 XiDSP]
Flash --> Verify[XiTest 回归]
Verify --> End([✓ 上线])
Fix --> Build
class Build,Compile xyL4
class Flash xyL0
class Verify xyL2
class Check xyWarn
class Fix xyError
class End xySuccess
class Start xyEnd
```
关键约束：
- 图中主流程节点（Build / Compile / Flash / Verify）全部属于跨 L4→L0→L2，这是合理的跨层流程，各自按所属产品层着色
- 唯一的"强对比色"是 xyWarn 菱形（金）+ xyError 红土 —— 因为它们在语义上就是"要引起注意"的分支
- 禁止在同一个分支里同时用 xyL5 紫 + xyL0 青 + xyError 红 等 3 个以上高饱和色
9.2.3 模板 C · 时序图（sequenceDiagram）
适用于：API 调用、协议交互。actor 背景按所属层级，消息线统一曦紫。
```mermaid
sequenceDiagram
autonumber
participant U as XiStudio (L4)
participant F as XiForge (L4)
participant D as XiDSP (L0)
U->>F: 编译请求
F-->>U: 编译进度
F->>D: 烧录 firmware
D-->>F: 烧录完成
F-->>U: ✓ 上线
```
约束：
- 每个 participant 的 括号里标注层级（(L4) / (L0)）以便读者心理建模
- 消息线色由主题统一设定，作者不要在 sequenceDiagram 里写 -->> 之外的自定义色
- sequenceDiagram 当前版本暂不支持 class X xyLn，故 actor 色由 xiyin-mermaid.js 的 actorBkg 全局玫瑰金 / 深夜蓝自动处理
9.3 支持的图类型
| 类型 | 场景 | 语法关键字 |
|---|---|---|
| 流程图 | 架构、工作流 | graph TB / LR |
| 时序图 | API 调用、协议交互 | sequenceDiagram |
| 状态图 | 生命周期、状态机 | stateDiagram-v2 |
| 甘特图 | 路线图、排期 | gantt |
| 饼图 | 分布、比例 | pie |
| 类图 | 数据结构 | classDiagram |
10. 图片
10.1 路径 & 命名
规则：
- 路径必须相对化（
./images/xxx.png），禁止绝对路径 - 文件名格式：
产品名-场景-版本.png，小写 + 连字符 - alt 文字必填（SEO + 无障碍）
- 建议附图注（斜体 + 编号）
- 每
.md的图片放在同级./images/子目录
10.2 尺寸控制（可选）
10.3 组图（Tabs 方案）
11. 产品命名规范（专有名词）
11.1 13 个产品名 · 唯一拼写
| 正确 ✅ | 错误 ❌ |
|---|---|
XiStudio |
xistudio / Xi Studio / XIstudio / Xi-Studio |
XiForge |
Xi Forge / xiforge |
XiAlgo |
Xi Algo / xialgo |
XiAlgo-FX |
XiAlgoFX / xialgo_fx |
XiDSP |
Xi DSP / xidsp |
XiCore |
Xi Core / xicore |
XiAmp |
Xi Amp / xiamp |
XiBox |
Xi Box / xibox |
XiTune |
Xi Tune / xitune |
XiTest |
Xi Test / xitest |
XiMic |
Xi Mic / ximic |
XiCal |
Xi Cal / xical |
XiProbe |
Xi Probe / xiprobe |
XiMind |
Xi Mind / ximind |
11.2 中英对照习惯
- 第一次出现时标注中文：
XiStudio（羲音工坊） - 后续可省略中文
- 型号写法：
XiDSP-D2/XiAmp Pro-12/XiCal 16ch
12. 链接
# 内部链接 · 使用相对路径
详见 [产品矩阵 V1.1](../10-product-matrix/overview.md)
# 外部链接 · 使用完整 URL + 自动短标题
官网：<https://xisound.com>
# 锚点
跳到 [8.2 行号 & 高亮](#82-行号-高亮)
13. Tabs（多视角内容）
=== "Python"
```python
import xi
```
=== "C"
```c
#include <xi.h>
```
=== "Bash"
```bash
xi --version
```
14. 脚注
15. 公式（可选）
支持 KaTeX 语法（通过 pymdownx.arithmatex）：
16. Notion 兼容降级指南
因 Notion 的 Markdown 导入支持有限，若文档需要同步到 Notion，请遵循：
| 特性 | Notion 支持 | 建议 |
|---|---|---|
| 标题/列表/加粗 | ✅ | 直接用 |
| 表格 | ⚠️ 简化 | 避免对齐标记与多级嵌套 |
| 代码块 | ✅ | 带语言标签即可 |
| Mermaid | ❌ | 需手动转为 Notion 原生图或截图 |
| Admonition | ❌ | 会降级为普通段落 |
| Frontmatter | ❌ | 会显示成纯文本，发布前手动删除 |
| Tabs | ❌ | 拆成多个子标题 |
推荐做法
MD 源文件保留全部豪华特性（用于 HTML 发布）； 需要同步 Notion 时，走脚本自动降级（本 Demo 暂不含，v1.1 补齐）。
17. 规范检查（提交前自查）
提交 PR 前请逐项核对：
- Frontmatter 完整（
title / description / level / category / status / author / date） -
level与内容厚度匹配（首页才给 L1A） - H1 唯一、无跳级
- 所有表格不含
<br>/ 嵌 HTML - 所有代码块带语言标签
- 所有图片是 Mermaid（架构图）或
./images/本地文件 - 产品名拼写符合 §11
- 内部链接用相对路径，未引用
AlgoDepartment/...绝对路径 - 本地
mkdocs serve打开无黄色警告 - §18 色彩合规：Mermaid 节点只用
xyL0-xyL5/xySuccess/xyWarn/xyError/xyEnd预设 class；MD 正文不含手写<span style="color">/<font color>；Admonition 不强改颜色
18. 色彩系统 · 3+1 规范（v1.1 新增）
本章目的
本站所有 UI 元素（Hero / 表格 / 代码 / Tab / Mermaid / Admonition）的颜色使用都受此规范约束。 作者写 MD 时只需套用预设 class，无需手动指定 hex 色值，自动继承品牌统一感。
18.1 总纲 · 三色 + 一背景
| 角色 | 颜色 | HEX | CSS 变量 | 核心用途 |
|---|---|---|---|---|
| 主色 · 音玫瑰金 | 🟡 玫瑰金 | #D4A574 |
--yin-color |
边框 / 竖条 / Tab 激活线 / 按钮 / 链接悬停 / 强调文字 |
| 辅色 · 曦紫霞 | 🟣 曦紫 | #9D4EDD |
--xi-color |
流程图连线 / 指向性箭头 / L5 云端层节点 |
| 点缀 · 声极光青 | 🔵 极光青 | #5DDECF |
--sheng-color |
所有 Admonition 统一标识色 / 输入类节点 / 成功态 / 代码函数名 |
| 背景 · 夜蓝 | ⚫ 夜蓝 | #0B1C2E / #14283F |
--night-deep / --night-mid |
Hero 底 / 代码块底 / Mermaid 画布 / 深色表头 |
18.2 Mermaid 图 · L0-L5 层级色规范
详细模板见 §9.2 三个典型场景（六层矩阵 / 分支流程 / 时序图）。
整图色规则（v1.1 强制）：
1. 一张图的节点色只能从 xyL0 ~ xyL5 + xySuccess / xyWarn / xyError / xyEnd 这 10 个预设 class 中挑选
2. 整图不得同时出现 3 个以上强饱和层级色（如同时 L0 青 + L4 紫 + L5 深紫）
3. 同层内多个模块必须同色，不再各自找色（避免"一层 4 模块 4 种色"）
4. 语义色（Success / Warn / Error）只用于关键节点（终态、判断、异常出口），中间节点一律走层级色
5. 连线颜色由 xiyin-mermaid.js 全局设为曦紫 #9D4EDD，作者禁止自定义线色
xiyin-mermaid.js 预置了 10 个 classDef，作者直接用 class Name xyLn 即可，无需写 classDef：
| Class | 对应产品层 | 代表产品 | 节点描边 | 节点填充 |
|---|---|---|---|---|
xyL0 |
芯片层 | XiDSP / XiCore | #2E8D7E 深极光青 |
#D8F0EA |
xyL1 |
硬件层 | XiAmp / XiBox | #5DDECF 极光青 |
#E8F4F1 |
xyL2 |
测试调音 | XiTune/Test/Mic/Cal/Probe | #E8C9A0 香槟金 |
#FBF4E8 |
xyL3 |
算法层 | XiAlgo | #D4A574 玫瑰金 |
#F5F2EA |
xyL4 |
工具层 | XiStudio / XiForge | #C77DFF 浅紫 |
#FAE8F0 |
xyL5 |
云端层 | XiMind | #9D4EDD 曦紫 |
#F0E6FA |
语义 class（用于流程分支）：
| Class | 语义 | 示例用法 |
|---|---|---|
xySuccess |
✅ 成功 / 通过 | 验收节点、打勾终态 |
xyWarn |
⚠️ 警告 / 判断 | 分支菱形、二次确认 |
xyError |
❌ 错误 / 阻断 | 失败终态、异常路径 |
xyEnd |
🔚 终止 / 输出 | 最终出口、归档态 |
用法示例（作者写法）：
```mermaid
graph TB
A[XiStudio IDE] --> B[XiAlgo FX]
B --> C[XiDSP D2]
C --> D[XiAmp Pro-12]
D --> E((上线验收))
class A xyL4
class B xyL3
class C xyL0
class D xyL1
class E xySuccess
```
连线色自动为曦紫 #9D4EDD（由 xiyin-mermaid.js 的 lineColor 全局设定，代表"贯穿的信息流"）。
18.3 色例图例（.mermaid-legend）
复杂图建议在下方加一个色例标签条帮助读者理解：
<div class="mermaid-legend">
<span class="xy-leg-item"><span class="xy-leg-dot xy-leg-l4"></span>L4 开发工具</span>
<span class="xy-leg-item"><span class="xy-leg-dot xy-leg-l3"></span>L3 算法</span>
<span class="xy-leg-item"><span class="xy-leg-dot xy-leg-l0"></span>L0 芯片</span>
<span class="xy-leg-item"><span class="xy-leg-dot xy-leg-l1"></span>L1 硬件</span>
<span class="xy-leg-item"><span class="xy-leg-dot xy-leg-success"></span>验收</span>
</div>
可用的色块 class：xy-leg-l0 ~ xy-leg-l5 / xy-leg-success / xy-leg-warn / xy-leg-error / xy-leg-end。
18.4 Admonition · 统一极光青（v1.1 变更）
自 v1.1 起废弃"八色 Admonition"，所有类型（note/info/tip/success/warning/danger/example/abstract/quote/failure/bug/question）统一使用极光青 #5DDECF 左竖条 + 图标，仅通过 Material 自带的图标和文字 label 区分类型：
原因：作者常在一页里混用多个 Admonition，八色会导致整页"花"而显得不严肃。统一后视觉节奏清爽，文字 label 本身足以表达语义。
18.5 代码高亮 · Pygments 3+1 配色映射
.md-typeset .highlight 下的 token 全局映射：
| Token | Pygments class | 颜色 | 说明 |
|---|---|---|---|
| 关键字 | .k .kc .kd .kn .kp .kr .kt |
#C77DFF 浅紫 |
int / void / return / class |
| 函数/类名 | .nf .fm .nc |
#5DDECF 极光青（粗） |
解决 C 代码函数名看不见的问题 |
| 字符串 | .s .s1 .s2 ... |
#E8C9A0 香槟金 |
"hello" |
| 数字 | .m .mi .mf ... |
#D4A574 玫瑰金 |
42 / 3.14 |
| 注释 | .c .c1 .cm ... |
#7A8A9B 灰（斜体） |
// 注释 |
| 变量 | .n .na .nb ... |
#F0F4F8 珍珠白 |
普通标识符 |
| 操作符 | .o .p .ow |
#B8C5D1 珍珠白暗 |
+ - * / |
18.6 完整场景对照表
| 场景 | 主色 | 辅色 | 点缀 | 背景 |
|---|---|---|---|---|
| Hero 文字大渐变 | 🟡 | — | — | ⚫ |
| 表格外框 + 左竖条 | 🟡 | — | — | 珍珠白 / ⚫ |
| Tab 选中底线 + 文字 | 🟡 | — | — | 浅玫瑰金 6% |
| 代码块左竖条 + 顶线左段 | 🟡 | — | — | ⚫ |
| 代码关键字 | — | 🟣 浅紫 | — | ⚫ |
| 代码函数名 | — | — | 🔵 | ⚫ |
| Mermaid 连线 | — | 🟣 | — | ⚫ |
| Mermaid 节点（按层级） | 🟡/🔵 等 | — | — | 浅底 |
| Admonition 左竖条 + 图标 | — | — | 🔵 | 珍珠白 |
| 链接悬停 | 🟡 | — | — | — |
| 成功态 / ✅ | — | — | 🔵 | — |
| 警告态 / ⚠️ | 🟡 | — | — | — |
| 错误态 / 🔴（仅此处破例） | — | — | 赤陶 #B87A6F |
— |
18.7 写作禁令（v1.1 新增）
- ❌ 禁止在 MD 里手写
<span style="color: red">、<font color="...">等内联色 - ❌ 禁止在 Mermaid 里自定义
fill:/stroke:hex 值（除非确实不属于 L0-L5 任一层） - ❌ 禁止给 Admonition 指定自定义颜色（统一极光青）
- ✅ 所有颜色表达必须通过 预设 class（xyLn / xySuccess / xy-leg-xx）或 语义 admonition 关键字（note/warning/...）
18.8 代码块视觉结构（主题层变更 · 作者无需感知）
v1.1 起主题将 Material 默认的双层代码块外框（.highlight + .highlighttable）折叠为单层：
.highlighttable的边框 / 阴影 / 圆角被透明化.highlight作为唯一视觉容器，承载：夜蓝底 + 玫瑰金左竖条 + 三色顶线 + 圆角外框- 行号列（
.linenos）仍保留，颜色为珍珠白灰，不再产生独立外框
作者写法无任何变化
你依然按 §8 规则写 ```c / ```python linenums="1" 即可，
所有双框合并逻辑在 xiyin-patch.css 自动生效。
18.9 变量与文件清单（维护者参考）
| 文件 | 职责 |
|---|---|
docs/assets/stylesheets/xiyin-brand.css |
3+1 色系 CSS 变量定义（--xi-color / --yin-color / --sheng-color / --night-*） |
docs/assets/stylesheets/xiyin-extra.css |
组件皮肤（Hero / 表格 / Tab / 标题卡 / 引用块） |
docs/assets/stylesheets/xiyin-patch.css |
v1.1 新增：Admonition 统一青 / 代码 Pygments 映射 / 代码块去双框 / Mermaid 图例 |
docs/assets/javascripts/xiyin-mermaid.js |
Mermaid 主题配置 + L0-L5 classDef 自动注入 |
修改任何颜色前，请先查
--xi-color / --yin-color / --sheng-color三变量是否满足需求，再考虑扩展新 class；禁止直接在组件 CSS 里写死 hex 色。
附录 A · 一键模板
复制下面的块，新建 .md 文件时直接粘贴作为起点：
---
title: 【填标题】
description: 【一句话说明】
level: l2
category: product
status: draft
author: AlgoDepartment
date: 2026-05-02
---
# 【与 title 一致或省略】
!!! abstract "摘要"
一句话说清本文要解决什么问题。
## 1. 背景
...
## 2. 设计
```mermaid
graph LR
A --> B
3. 验收
- 关键点 1
- 关键点 2 ```
附录 B · 参考
- 权威视觉规范：
converttool/ref/XIYIN-DESIGN-SPEC.mdv1.3 - 纲领需求：
06_docs/文档体系搭建.md - 本规范版本：v1.1 · 2026-05-05 · Xisound AlgoDepartment
附录 C · 版本历史
| 版本 | 日期 | 要点 |
|---|---|---|
| v1.0 | 2026-05-02 | 首版发布，建立 frontmatter / 标题 / Admonition / Mermaid / 代码块等基础规范 |
| v1.1 | 2026-05-05 | 新增 §18 色彩系统 · 3+1 规范；Admonition 统一极光青；Mermaid L0-L5 classDef 预设；C 代码高亮重写；代码块去双层框 |