MD Writing Spec · v2.0

Markdown 写作规范 v2.0

作者版 · 9 条视觉决议落地 · 唯一权威写作契约

适用范围:AlgoDepartment/06_docs/** 下所有 .md 文件 · 受众:所有文档作者

Markdown 写作规范 v2.0(作者版)

本文档定位

受众:所有文档作者(算法部 / 产品中心 / 硬件 / 测试 / 商务 / 交付等)
内容:仅聚焦 MD 源文件的格式契约(Frontmatter / 标题 / 表格 / 代码块 / Mermaid / 命名 / 9 条视觉组件)
不含:色彩细节、CSS 变量、Web 主题实现 → 请查阅 3+1 品牌色彩系统 v1.2
地位:本文是所有 .md 文件的唯一权威写作契约,违反的 PR 会被打回

v2.0 版本要点(2026-05-11)

§5 Admonition 由「8 种统一极光青」升级为「12 类按 6 组语义配色」(信息 / 提示 / 警告 / 危险 / 示例 / 引用)— 落地决议 3
§7.2b 新增:术语网格 .xy-glossary 卡片化替代定义列表 — 落地决议 2
§9.4 新增:Mermaid 放大按钮(主题自动注入,作者无感)— 落地决议 7
§9.5 新增:双轨甘特图(Mermaid gantt + .xy-gantt 自绘)— 落地决议 6
§9.6 新增:Subgraph 子图浅产品色底(xySgL0~xySgL5)— 落地决议 5
§15 重写:数学公式双轨方案(Unicode/HTML + KaTeX 选择性加载)— 落地决议 8
§16 新增:.xy-quote 引言/箴言卡 — 落地决议 1
§17 新增:.xy-stack 产品 6 色层级栈 — 落地决议 9
§10 Tabs 激活态视觉升级(主题自动,作者无感)— 落地决议 4
frontmatter 升级:首次集成命名规范方案 4 完整字段(doc_id / audience / owner / last_review / version / legacy_doc_id)
不变:1-4 章核心契约(总则 / Frontmatter 必填字段 / Level 体系 / 标题规范)100% 向下兼容 v1.1

1. 总则(Do & Don't)

✅ 必须	❌ 禁止
每篇文档必须有 frontmatter(完整 §2 必填字段)	使用 ASCII 框图(`╔═╗ ┌─┐`)表达架构
H1 只用一次(或交给 frontmatter.title)	标题跳级(H2 → H4)
用 Mermaid 画流程 / 架构图	把架构图做成截图后贴 png
用 Admonition 表达提示/警告(§5 6 组语义)	用 `> ⚠️ 警告:...` 这种 emoji-引用 hack
表格保持简洁单元格	表格单元内使用 `<br>` 或嵌 HTML
复杂术语清单用 `.xy-glossary`(§7.2b)	用复杂表格强行表达术语
引用经典/箴言用 `.xy-quote`(§16)	用大段裸 blockquote
产品名写规范拼写(`XiStudio`)	写成 `xistudio / Xi Studio / XIstudio`
所有颜色通过预设 class 表达	手写 `<span style="color">` / `<font color>` 内联色
简单公式用 Unicode + HTML(§15)	复杂公式无 KaTeX 标记直接写 LaTeX

2. Frontmatter(YAML · 必填)

每篇 .md 顶部必须有 YAML frontmatter。字段分为核心必填、命名规范方案 4 字段(v2.0 新增)、Hero 专用、可选 4 类。

2.1 核心必填字段(向下兼容 v1.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: 作者或团队
date: YYYY-MM-DD                 # 最近一次实质更新日期
---

2.2 命名规范方案 4 字段(v2.0 新增 · 推荐填写)

决议来源:docs-naming-convention.md 方案 4

doc_id: SPEC-XXXX-YYY-NNN   # 稳态文档身份证(可选,但发布级文档强烈推荐)
audience: 受众标签(逗号分隔) # 如:doc-author, web-frontend, ui-designer
owner: 所有人或团队          # 与 author 区分:author=本次作者, owner=长期维护方
last_review: YYYY-MM-DD     # 最后一次审阅日期(可与 date 不同)
version: 2.0                 # 文档版本号(独立于产品版本)
tags: [spec, markdown]      # 检索标签
legacy_doc_id: 旧路径或旧 ID # 迁移文档保留旧 ID 链路(便于跨版本追溯)

doc_id 格式约定(详见 doc-numbering.md): - 稳态文档:<TYPE>-<DOMAIN>-<NUM> 如 SPEC-MD-WRITING-001 / ARCH-XISTUDIO-CORE-002 - 过程文档(_dev/ 下):<TYPE-PREFIX>-<NUM> 如 PHASE-008 / ADR-014 / RUNBOOK-003 - 文件路径变,doc_id 不变(便于历史追溯)

2.3 Hero 专用字段(仅当 `level: l1a` 或 `l1b` 时使用)

hero_show: true
hero_label: Documentation · v1.0
hero_title: 主标题
hero_sub: 副标题一句话
hero_meta: "作者:XX · 日期:XX · 版本:XX"
hero_tagline: From Silicon to Sound
hero_stats:
  - num: "6"
    label: 产品层级
  - num: "13"
    label: 产品线

2.4 可选字段

product: XiStudio
layer: L4

frontmatter 三个最易错的点

--- 必须独占一行,不能前后有空格
level 必须是小写:l1a / l1b / l2 / l3
hero_show: true 不写就不渲染 Hero

3. 文档分级(Level 体系)

Level	场景	Hero 形态	典型文档
L1A	站点首页 / 大板块首页	星空 + 三色涟漪 + 统计数字	`index.md` 根首页
L1B	主题级重磅文档	简洁渐变 Hero	产品矩阵、白皮书、规范
L2	章节级长文	无 Hero,标题带品牌加粗线	单个产品 Datasheet
L3	条目级、备忘、术语表	纯内容	术语表、FAQ 单条

选级原则:不确定就选 L2。L1A/L1B 的 Hero 有视觉重量,不应泛滥。

4. 标题规范

# H1 — 仅用一次

## 1. H2 章节(带编号)

### 1.1 H3 子章节

#### H4 细分点(≤ 4 层,不鼓励更深)

规则: - 标题必须连续递进,禁止跳级(## → ####) - H2/H3 推荐加编号(## 1. XXX),便于 TOC 与交叉引用 - 标题内不使用 emoji - 同篇标题文本唯一,避免 TOC 锚点冲突

5. Admonition · 12 类按 6 组语义配色(v2.0)

决议来源:format-spec-changelog.md 决议 3 · 配色实现:brand-color-system.md §4

5.1 6 组语义配色总览

组	包含的关键字	主色	用途
信息组	`note` `abstract` `info`	紫霞	一般信息陈述、架构说明、上下文
提示组	`tip` `success` `question`	极光青	给作者的建议、成功状态、待回答
警告组	`warning`	玫瑰金	注意事项、边界条件、副作用
危险组	`failure` `danger` `bug`	赤陶	错误、阻断、Bug
示例组	`example`	古铜金	代码示例、用例、参考实现
引用组	`quote`	中性灰	简短引用(长引用用 `.xy-quote`)

5.2 标准写法(12 类全集)

!!! note "注记(信息组 · 紫霞)"
    一般信息陈述

!!! abstract "摘要(信息组 · 紫霞)"
    文档开头纲要

!!! info "信息(信息组 · 紫霞)"
    补充背景知识

!!! tip "最佳实践(提示组 · 极光青)"
    推荐做法、经验之谈

!!! success "验收通过(提示组 · 极光青)"
    某项检查/测试已通过

!!! question "待回答(提示组 · 极光青)"
    悬而未决的问题

!!! warning "注意事项(警告组 · 玫瑰金)"
    有风险但可继续

!!! failure "失败(危险组 · 赤陶)"
    某项任务失败

!!! danger "严重警告(危险组 · 赤陶)"
    禁止忽略

!!! bug "已知 Bug(危险组 · 赤陶)"
    待修复的 Bug

!!! example "示例(示例组 · 古铜金)"
    代码/案例/步骤演练

!!! quote "引用(引用组 · 中性灰)"
    简短引文(>50 字请用 .xy-quote 见 §16)

5.3 可折叠版本(长内容)

??? info "点击展开 · 详细说明"
    默认折叠

???+ tip "点击展开 · 默认展开"
    `???+` 默认展开但可折叠

关于颜色

所有 Admonition 的视觉颜色由主题自动统一处理(详见 brand-color-system.md §4)。 作者只需正确选用关键字,严禁手写 admonition 颜色。

6. 列表

6.1 无序列表 · 统一用 `-`

- 一级
  - 二级(两个空格缩进)
    - 三级

6.2 有序列表 · 统一用 `1.`

1. 第一步
2. 第二步
3. 第三步

6.3 任务清单

- [x] 已完成项
- [ ] 未完成项

7. 表格

7.1 基本规则

单元格不换行(需要换行请改用列表或拆行)
单元格不嵌 HTML 标签(  / <img> /  均禁止)
对齐标记统一(|:---|:---:|---:| 左/中/右)
表头必须写

| 英文名 | 中文名 | 层级 | 定位 |
|:------|:------|:----:|:-----|
| XiStudio | 羲音工坊 | L4 | 可视化 IDE 平台 |
| XiDSP | 羲音芯 | L0 | 音频专用 DSP 芯片 |

7.2 复杂信息的替代方案 A · 定义列表

需要合并单元格、多行描述时,改用 定义列表:

XiStudio
: 羲音工坊 · L4 开发工具层
: 可视化音频算法 IDE

XiDSP
: 羲音芯 · L0 芯片基础层
: 车规级音频 DSP

7.2b 复杂信息的替代方案 B · 术语网格 `.xy-glossary`(v2.0 新增)

决议来源:format-spec-changelog.md 决议 2

适用场景:大量术语并列(>5 项)、需要层级标签、希望卡片化扫读 — 比定义列表更醒目、比表格更紧凑。

作者写法(需 md_in_html 已启用,主题已默认开启):

<div class="xy-glossary" markdown="1">

<div class="xy-term" markdown="1">
<span class="xy-term-name">DSP <span class="xy-term-tag l0">L0</span></span>
Digital Signal Processing,数字信号处理。
</div>

<div class="xy-term" markdown="1">
<span class="xy-term-name">Mixer <span class="xy-term-tag l3">L3</span></span>
混音模块,负责多通道信号矩阵混合。
</div>

<div class="xy-term" markdown="1">
<span class="xy-term-name">XiStudio <span class="xy-term-tag l4">L4</span></span>
羲音工坊 · 可视化音频算法 IDE。
</div>

</div>

层级标签 class: - .xy-term-tag.l0 ~ .xy-term-tag.l5 与产品 6 色对齐(详见 brand-color-system.md §3.3)

何时不要用: - ❌ 仅有 1-3 个术语 → 用普通段落 - ❌ 术语之间有强对比关系 → 用表格 - ❌ 术语带代码示例 → 用 <details> + 代码块

8. 代码块

8.1 必须带语言标签

```python
def mix(a, b):
    return a + b
```

支持的语言标签:python / c / cpp / csharp / typescript / javascript / bash / powershell / bat / yaml / json / toml / ini / markdown / mermaid / diff / sql

8.2 行号 & 高亮

```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

代码高亮配色

作者无需关心代码块内配色。主题已对 C/Python/Shell 等做夜蓝底 + 高对比度 token 着色(详见 brand-color-system.md §5)。

9. Mermaid 架构图(唯一合法的"图")

9.1 规范

禁止使用 ASCII 框图(╔═╗、┌─┐)
禁止把架构图做成截图 后当 png 贴
必须用 Mermaid 写成代码块,渲染为 SVG(可搜索、可主题化)

9.2 配色总则(v1.1 起强制 L0-L5 层级色)

一张图只服从"产品层级色 + 语义分支色"两条规则,禁止手写 hex。所有节点必须挂 xyL0 ~ xyL5 或 xySuccess / xyWarn / xyError / xyEnd 之一。这 10 个 class 已由主题预置。

核心原则: 1. 整图主色单一:节点只在一到两个相邻层级色系内 2. 同层模块同色:XiAmp/XiBox 都是 L1 → 都用 xyL1 3. 语义色仅点缀:xySuccess/xyError 只用于关键终态 4. 跨层连线:统一曦紫(由主题 lineColor 自动) 5. 判断菱形:统一用 xyWarn

9.2.1 模板 A · 六层产品矩阵

```mermaid
graph TB
    subgraph L5_["L5 · 云端"]
      XiMind[XiMind]
    end
    subgraph L4_["L4 · 工具"]
      XiStudio[XiStudio]
      XiForge[XiForge]
    end
    subgraph L0_["L0 · 芯片"]
      XiDSP[XiDSP]
    end

    XiMind --> XiStudio --> XiForge --> XiDSP

    class XiMind xyL5
    class XiStudio,XiForge xyL4
    class XiDSP xyL0
```

9.2.2 模板 B · 带判断分支流程

```mermaid
graph LR
    Start([开始]) --> Build[XiStudio 导出]
    Build --> Check{参数合规?}
    Check -- 是 --> Compile[XiForge 编译]
    Check -- 否 --> Fix[回工坊修正]
    Compile --> Flash[烧录 XiDSP]
    Flash --> End([✓ 上线])

    class Build,Compile xyL4
    class Flash xyL0
    class Check xyWarn
    class Fix xyError
    class End xySuccess
    class Start xyEnd
```

9.2.3 模板 C · 时序图

```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) 便于读者心理建模。消息线色由主题统一,禁止自定义。

9.3 支持的图类型

类型	场景	语法关键字
流程图	架构、工作流	`graph TB / LR`
时序图	API 调用、协议交互	`sequenceDiagram`
状态图	生命周期、状态机	`stateDiagram-v2`
甘特图	路线图、排期	`gantt`(详见 §9.5)
饼图	分布、比例	`pie`
类图	数据结构	`classDiagram`

9.4 Mermaid 放大按钮(v2.0 主题自动注入,作者无感)

决议来源:format-spec-changelog.md 决议 7

主题(xiyin-mermaid-zoom.js)会自动给所有 .mermaid 容器右上角注入 ⛶ 放大 按钮,点击后在全屏 modal 中显示原图,支持 ESC 关闭。

作者无需任何额外动作 — 只要按 §9.2 模板正常写 mermaid 代码块即可。

9.5 Subgraph 子图浅产品色底(v2.0 显式声明)

决议来源:format-spec-changelog.md 决议 5

当图中使用 subgraph 分组时,在图末尾用 class <subgraphId> xySgLn; 给子图块加浅色底,与节点 xyLn 配套形成层级递进。

6 套子图 class(主题已预置): - xySgL0 浅深极光青 / xySgL1 浅极光青 / xySgL2 浅香槟金 - xySgL3 浅金 / xySgL4 浅紫 / xySgL5 浅曦紫

完整示例(子图 + 节点双重标色):

```mermaid
flowchart LR
    subgraph SG0 [前端层]
      A[UI]
    end
    subgraph SG3 [后端层]
      B[API]
    end
    A --> B

    class SG0 xySgL1
    class SG3 xySgL3
    class A xyL1
    class B xyL3
```

完整 6 层示例详见 brand-color-system.md §3.2。

9.6 双轨甘特图(v2.0 新增)

决议来源:format-spec-changelog.md 决议 6

场景	推荐方案	工作量
一般里程碑 / Roadmap 草图	轨道 A · Mermaid `gantt`(默认推荐)	5 行
战略级 Roadmap / 客户提案	轨道 B · `.xy-gantt` HTML 自绘(精致版)	~20 行

轨道 A · Mermaid gantt(主题已注入品牌色 themeVariables,作者无需关心):

```mermaid
gantt
    title Xistudio Roadmap 2026
    dateFormat YYYY-MM
    section P1
    需求评审 :done, p1a, 2026-01, 2M
    架构设计 :active, p1b, 2026-03, 2M
    section P2
    试点开发 :p2a, 2026-05, 3M
```

主题自动渲染:done = 极光青 / active = 玫瑰金渐变 / planned = 虚线浅卡。

轨道 B · .xy-gantt HTML 自绘(精致版):

<div class="xy-gantt" markdown="1">
<div class="xy-gantt-row" markdown="1">
<span class="xy-gantt-label">P0 基础设施</span>
<div class="xy-gantt-track">
<div class="xy-gantt-bar done" style="left:0%; width:25%;">已交付</div>
</div>
</div>
<div class="xy-gantt-row" markdown="1">
<span class="xy-gantt-label">P1 高优文档</span>
<div class="xy-gantt-track">
<div class="xy-gantt-bar active" style="left:25%; width:30%;">进行中</div>
</div>
</div>
<div class="xy-gantt-row" markdown="1">
<span class="xy-gantt-label">P2 业务层</span>
<div class="xy-gantt-track">
<div class="xy-gantt-bar planned" style="left:55%; width:35%;">计划</div>
</div>
</div>
</div>

bar class:.done(极光青实色) / .active(玫瑰金渐变 + 脉冲) / .planned(虚线浅卡)。

10. 图片

10.1 路径 & 命名

![XiStudio 主界面截图](./images/xistudio-main-ui-v1.png)
*图 1 · XiStudio 主界面(v1.0)*

规则: - 路径必须相对化(./images/xxx.png),禁止绝对路径 - 文件名格式:产品名-场景-版本.png,小写 + 连字符 - alt 文字必填(SEO + 无障碍) - 建议附图注(斜体 + 编号) - 每 .md 的图片放在同级 ./images/ 子目录

10.2 尺寸控制

![XiAmp 外观](./images/xiamp-pro12.png){ width=640 }

10.3 组图(Tabs)

=== "正面"
    ![正面](./images/xiamp-front.png)

=== "背面"
    ![背面](./images/xiamp-back.png)

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](../00-vision/product-matrix.md)

# 外部链接 · 完整 URL
官网:<https://xisound.com>

# 锚点
跳到 [8.2 行号 & 高亮](#82-行号-高亮)

13. Tabs(多视角内容)

=== "Python"
    ```python
    import xi
    ```

=== "C"
    ```c
    #include <xi.h>
    ```

=== "Bash"
    ```bash
    xi --version
    ```

v2.0 起 Tabs 激活态视觉升级:玫瑰金实色填充 + 白字 + 底部小三角(主题自动,作者无感)。落地决议 4。

14. 脚注

这是一段含脚注的说明[^1]。

[^1]: 脚注内容,支持 Markdown 格式。

15. 数学公式 · 双轨方案(v2.0 重写)

决议来源:format-spec-changelog.md 决议 8

场景	推荐方案	加载体积
行内简单公式(变量、上下标)	轨道 A · Unicode + HTML	0KB
简单分数	轨道 A · `.xy-frac` CSS 分数线	0KB
矩阵 / 积分 / 求和 / 复杂分数	轨道 B · KaTeX	~280KB(按需)

15.1 轨道 A · Unicode + HTML(零依赖)

- 信号能量:E = ∑ x[n]² (用 Unicode `∑`)
- 滤波器:H<sub>∞</sub>(z) = b<sub>0</sub> + b<sub>1</sub> z<sup>-1</sup>
- 简单分数:<span class="xy-frac"><span class="xy-frac-num">1</span><span class="xy-frac-den">2π</span></span>

常用 Unicode 数学符号:∑ ∏ ∫ ∮ √ ∞ ± × ÷ ≤ ≥ ≠ ≈ ∂ ∇ ∈ ∉ ∪ ∩ ⊂ ⊃ ⇒ ⇔ → ←

何时用轨道 A:90% 算法部公式都是简单上下标 / 求和符号,不需要 KaTeX。

15.2 轨道 B · KaTeX(按需启用)

仅当文档含有矩阵、积分、希腊字母组合等复杂公式时,在 frontmatter 加:

katex: true

然后即可使用标准 LaTeX 语法:

内联:$E = mc^2$

块级:
$$
H(z) = \frac{b_0 + b_1 z^{-1}}{1 + a_1 z^{-1}}
$$

KaTeX CDN 由主题按 katex: true frontmatter 字段动态加载(详见 nav-display-spec.md §3)。

16. 引言/箴言卡 `.xy-quote`(v2.0 新增)

决议来源:format-spec-changelog.md 决议 1

适用场景:引用经典语句、产品箴言、客户原话、文献名言 — 视觉上有「仪式感」,与 Material 默认 blockquote 形成层级。

作者写法:

<div class="xy-quote" markdown="1">
<div class="xy-quote-content" markdown="1">
人因梦想而伟大,因学习而成长,因行动而成就。
</div>
<span class="xy-quote-author">米开朗基罗</span>
</div>

支持嵌套引用(引文中引文):

<div class="xy-quote" markdown="1">
<div class="xy-quote-content" markdown="1">
正如某位先哲所说:
<div class="xy-quote-nested" markdown="1">
"知者不博,博者不知。"
</div>
所以我们追求的是深度,不是广度。
</div>
<span class="xy-quote-author">某产品宣言</span>
</div>

何时不要用: - ❌ 短引用(<50 字)→ 用 !!! quote admonition - ❌ 代码引用 → 用代码块 - ❌ API 响应示例 → 用 <details> + JSON 代码块

17. 产品 6 色层级栈 `.xy-stack`(v2.0 新增)

决议来源:format-spec-changelog.md 决议 9

适用场景:表达「L0 平台 → L5 用户」「数据层 → UI 层」「物理层 → 应用层」等多层级架构 — 比表格更视觉化、比 Mermaid 更紧凑。