跳转至
MD Writing Spec · v1.1

Markdown 写作规范 v1.1

作者版 · 仅聚焦 MD 格式 · 色彩规范已独立为 brand-color-system.md
适用范围：AlgoDepartment/06_docs/** 下所有 .md 文件 · 受众：所有文档作者

Markdown 写作规范 v1.1（作者版）

本文档定位

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

v1.1 版本要点（2026-05-05）

  • Mermaid 图引入 L0-L5 层级 classDef 预设（作者直接 class X xyL3 即可，不用写 classDef）
  • Admonition 八色视觉统一为极光青（作者写法不变，主题自动处理）
  • 本规范 拆分为两份：作者版（本文件，无色彩）+ Web 主题版（brand-color-system.md）

1. 总则（Do & Don't）

✅ 必须 ❌ 禁止
每篇文档必须有 frontmatter 使用 ASCII 框图（╔═╗ ┌─┐）表达架构
H1 只用一次（或交给 frontmatter.title） 标题跳级（H2 → H4）
用 Mermaid 画流程 / 架构图 把架构图做成截图后贴 png
用 Admonition 表达提示/警告 用 > ⚠️ 警告：... 这种 emoji-引用 hack
表格保持简洁单元格 表格单元内使用 <br> 或嵌 HTML
产品名写规范拼写（XiStudio） 写成 xistudio / Xi Studio / XIstudio
所有颜色通过预设 class 表达 手写 <span style="color"> / <font color> 内联色

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: 作者或团队
date: YYYY-MM-DD                 # 最近一次实质更新日期
---

2.2 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.3 可选字段

version: v1.0
product: XiStudio
layer: L4
tags: [dsp, mixer, api]

frontmatter 三个最易错的点

  1. --- 必须独占一行，不能前后有空格
  2. level 必须是小写：l1a / l1b / l2 / l3
  3. 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（提示框）

只使用以下 8 种，不允许自创关键字：

!!! note "注记"
    普通笔记

!!! info "信息"
    补充背景知识

!!! tip "最佳实践"
    推荐做法、经验之谈

!!! success "验收通过"
    某项检查/测试已通过

!!! warning "注意事项"
    有风险但可继续

!!! danger "严重警告"
    禁止忽略

!!! example "示例"
    代码/案例/步骤演练

!!! abstract "摘要"
    文档开头纲要

可折叠版本（长内容）：

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

关于颜色

所有 Admonition 的视觉颜色由主题自动统一处理（详见 brand-color-system.md §4）。 作者只需正确使用关键字，无需关心具体颜色。

6. 列表

6.1 无序列表 · 统一用 -

- 一级
  - 二级（两个空格缩进）
    - 三级

6.2 有序列表 · 统一用 1.

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

6.3 任务清单

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

7. 表格

7.1 基本规则

  • 单元格不换行（需要换行请改用列表或拆行）
  • 单元格不嵌 HTML 标签（<br> / <img> / <span> 均禁止）
  • 对齐标记统一（|:---|:---:|---:| 左/中/右）
  • 表头必须写
| 英文名 | 中文名 | 层级 | 定位 |
|:------|:------|:----:|:-----|
| XiStudio | 羲音工坊 | L4 | 可视化 IDE 平台 |
| XiDSP | 羲音芯 | L0 | 音频专用 DSP 芯片 |

7.2 复杂信息的替代方案

需要合并单元格、多行描述时，改用 定义列表 或 卡片网格：

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

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

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
饼图 分布、比例 pie
类图 数据结构 classDiagram

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

14. 脚注

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

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

15. 公式

支持 KaTeX 语法（通过 pymdownx.arithmatex）：

行内公式：$E = mc^2$

块级公式：

$$
SNR = 20 \cdot \log_{10}\left(\frac{A_{signal}}{A_{noise}}\right)
$$

16. Notion 兼容降级指南

因 Notion 的 Markdown 导入支持有限：

特性 Notion 支持 建议
标题/列表/加粗 ✅ 直接用
表格 ⚠️ 简化 避免对齐标记与多级嵌套
代码块 ✅ 带语言标签即可
Mermaid ❌ 需手动转为截图
Admonition ❌ 会降级为普通段落
Frontmatter ❌ 发布前手动删除
Tabs ❌ 拆成多个子标题

推荐做法

MD 源文件保留全部豪华特性（用于 HTML 发布）；同步 Notion 时走脚本自动降级。

17. 规范检查（提交前自查）

提交 PR 前请逐项核对：

  • Frontmatter 完整（title / description / level / category / status / author / date）
  • level 与内容厚度匹配（首页才给 L1A）
  • H1 唯一、无跳级
  • 所有表格不含 <br> / 嵌 HTML
  • 所有代码块带语言标签
  • 所有图片是 Mermaid 或 ./images/ 本地文件
  • 产品名拼写符合 §11
  • 内部链接用相对路径
  • 本地 mkdocs serve 打开无黄色警告
  • 色彩合规：Mermaid 节点只用 xyL0-xyL5 / xySuccess / xyWarn / xyError / xyEnd；MD 正文不含手写 <span style="color"> / <font color>；Admonition 不强改颜色（详见 brand-color-system.md）

附录 A · 一键模板

新建 .md 文件时直接粘贴作为起点：

---
title: 【填标题】
description: 【一句话说明】
level: l2
category: product
status: draft
author: AlgoDepartment
date: 2026-05-05
---

# 【与 title 一致或省略】

!!! abstract "摘要"
    一句话说清本文要解决什么问题。

## 1. 背景

...

## 2. 设计

```mermaid
graph LR
    A --> B

3. 验收

  • 关键点 1
  • 关键点 2 ```

附录 B · 参考

附录 C · 版本历史

版本 日期 要点
v1.0 2026-05-02 首版，建立 frontmatter / 标题 / Admonition / Mermaid / 代码块等基础规范（原 00-spec/md-style-guide.md）
v1.1 2026-05-05 从原 md-style-guide.md 拆分出色彩规范为独立文件；本版仅含作者向格式契约；Mermaid 新增 L0-L5 模板与整图色规则

md-writing-spec.md · 作者版 · v1.1 · 2026-05-05 · Xisound AlgoDepartment