深入剖析 openvscode-server 的 Markdown 语法着色：test.md 夹具与 Colorize 回归测试全解

• 开发工具
• IDE
• 代码编辑器
• 后端

openvscode-server 内置了完整的 VS Code 编辑器与全部语言扩展，其中 Markdown 的语法高亮由 TextMate 文法与 Tree-sitter 双引擎驱动，并通过快照式的 colorize 回归测试保证每一次改动都“着色不变”。本文以测试夹具 test.md 为标本，逐行还原它覆盖的 Markdown 语法要素，并结合测试源码与着色基线结果，讲清楚“一段 Markdown 文本最终是如何被切成带 scope 的 token、再映射成主题颜色的”。读完本文，你将掌握 Markdown 语法着色的 scope 体系、主题颜色映射规则，以及 openvscode-server 中 colorize 回归测试的完整运行机制。

一、test.md 是什么：一份“语法标本”而非普通文档

test.md位于 extensions/vscode-colorize-tests/test/colorize-fixtures/ 目录下。这个目录名为colorize-fixtures（着色测试夹具），存放着几十份覆盖不同语言的文件，包括basic.java、test.py、test.ts、test.html、test.yaml等。它们不是给人阅读的示例文档，而是喂给高亮引擎的输入样本：引擎对每一份样本执行分词，输出“每个字符的 scope 与颜色”快照，再与基线 JSON 逐字符比对。

test.md的特殊之处在于，它是专门为 Markdown 语法高亮设计的“语法大全”：106 行文本里几乎塞进了 Markdown 的全部语法构件——ATX/Setext 标题、自定义标题 ID、锚点链接、内嵌 HTML、三种无序列表符号、嵌套列表、有序列表、行内格式、围栏代码块、波浪线代码块、缩进代码块、块引用嵌套、水平分割线、图片、表格、定义列表与缩写。任何一条语法规则在这份文件里都能找到对应用例，因此它也是排查“某条 Markdown 语法为什么不亮”的首选复现样本。

二、test.md 覆盖的 Markdown 语法全景

下面按文件本身的行文顺序，把test.md逐段拆解成一份“语法-着色”对照清单。

2.1 标题体系：ATX 标题、右侧闭合井号与自定义 ID

# Header 1 # ## Header 2 ## ### Header 3 ### (Hashes on right are optional) ## Markdown plus h2 with a custom ID ## {#id-goes-here} [Link back to H2](#id-goes-here)

• #到######的 ATX 标题逐级覆盖；
• 右侧的闭合#被明确标注为可选（注释(Hashes on right are optional)），着色器需同时正确处理左右两端的#；
• ## ... ## {#id-goes-here}演示带自定义 ID 的标题：括号里的{#id-goes-here}会被解析为标题元数据，而后一行[Link back to H2](#id-goes-here)的锚点链接正是指向该 ID——同一份样本内自洽地测试了“ID 定义”与“锚点引用”两种语法。

从基线结果 test_md.json 可以看到，标题被切成多个 scope 片段：#是punctuation.definition.heading.markdown，标题文本是entity.name.section.markdown，整行包裹在markup.heading.markdown heading.1.markdown（一级）到heading.3.markdown（三级）之间；链接部分则落入meta.link.inline.markdown与markup.underline.link.markdown。

2.2 Setext 标题：===与---

### Alternate heading styles: Alternate Header 1 ================== Alternate Header 2 ------------------

test.md一并验证了 Setext 风格标题：下一行的=或-下划线把上一行文本提升为一级/二级标题。注意此处与后文水平分割线（同为-或*组成的行）的区别——着色器需要区分“下划线式标题”与“分割线”，这依赖上下文规则。

2.3 内嵌 HTML：最复杂的嵌入式作用域

<!-- html madness --> <div class="custom-class" markdown="1"> <div> nested div </div> <script type='text/x-koka'> function( x: int ) { return x*x; } </script> This is a div _with_ underscores and a & <b class="bold">bold</b> element. <style> body { font: "Consolas" } </style> </div>

这是test.md中最考验着色引擎的部分：

• <!-- html madness -->是 HTML 注释，在结果中被识别为comment.block.html；
• <div markdown="1">演示带markdown属性的块级标签：标签本身走meta.tag.structure.div.start.html，class属性名是meta.attribute.class.html，双引号字符串是string.quoted.double.html（dark 主题下为蓝色#0000FF）；
• <script type='text/x-koka'>内部是 JavaScript 风格代码，走meta.embedded.block.html+meta.tag.metadata.script.start.html，单引号字符串为string.quoted.single.html；
• 标签中间混排的普通文本This is a div _with_ underscores依然是 Markdown 段落，其中的_with_仍会被解析为斜体——内嵌 HTML 与 Markdown 行内格式共存于同一块；
• <style>内嵌 CSS 代码块同理，通过 markdown-basics 的 package.json 中embeddedLanguages映射声明为source.css。

2.4 列表：符号三态与嵌套

* Bullet lists are easy too - Another one + Another one + nested list

三种无序列表符号*、-、+全部覆盖，并演示了 4 空格缩进产生的嵌套列表。基线结果显示列表符号被标记为markup.list.unnumbered.markdown punctuation.definition.list.begin.markdown，且在 dark_plus 主题下为青色系#6796E6、light 主题下为#0451A5；嵌套列表的 scope 会叠加为markup.list.unnumbered.markdown markup.list.unnumbered.markdown。

2.5 段落与行内格式：下划线陷阱

This is a paragraph, which is text surrounded by whitespace. Paragraphs can be on one line (or many), and can drone on for hours. Now some inline markup like _italics_, **bold**, and `code()`. Note that underscores in_words_are ignored.

• 多行段落：强调“由空白包围的文本即段落”，可跨行；
• _italics_解析为markup.italic.markdown（dark 主题#C586C0、light 主题#800080）；
• **bold**解析为markup.bold.markdown（dark 主题#569CD6、light 主题#000080）；
• `code()`是行内代码；
• 关键用例：in_words_are_ignored——夹在单词中间的单个下划线不得被当作斜体定界符。这条规则由 TextMate 文法的上下文匹配保证，是 Markdown 行内格式解析的经典边界。

2.6 围栏代码块：四反引号 + MIME 类型

````application/json { value: ["or with a mime type"] }

用四个反引号开头的围栏代码块，语言标识直接写成 MIME 类型 `application/json`。结果中被标记为 `markup.fenced_code.block.markdown`，语言名落入 `fenced_code.block.language` scope——这验证了围栏代码块既支持短语言名也支持 MIME 形式的信息头。 ### 2.7 块引用：可嵌套，可嵌列表 ```markdown > Blockquotes are like quoted text in email replies >> And, they can be nested ``` `>` 一级块引用与 `>>` 二级嵌套块引用；scope 相应叠加为 `markup.quote.markdown` 与 `markup.quote.markdown markup.quote.markdown`，行首 `>` 单独标记为 `punctuation.definition.quote.begin.markdown`。 ### 2.8 有序列表与缩进代码块 ```markdown 1. A numbered list > Block quotes in list 2. Which is numbered 3. With periods and a space ``` 有序列表 `1.` 走 `markup.list.numbered.markdown`；列表项内 4 空格缩进的 `> Block quotes in list` 被识别为“列表中的块引用”，scope 为 `markup.list.numbered.markdown markup.quote.markdown`，证明块级结构可以跨类型嵌套。 ```markdown // Code is just text indented a bit which(is_easy) to_remember(); ``` 4 空格缩进的整段文本是“缩进代码块”——这里 `test.md` 特意写入了伪代码，用于验证**缩进代码块内部不再进行任何 Markdown 行内解析**。 ### 2.9 波浪线围栏代码块 ```markdown ~~~ // Markdown extra adds un-indented code blocks too if (this_is_more_code == true && !indented) { // tild wrapped code blocks, also not indented } ~~~ ``` 与反引号围栏并列的 `~~~` 波浪线围栏，文件注释点明其语义是“Markdown Extra 风格的不缩进代码块”。 ### 2.10 尾随空格换行（诗歌式硬换行） ```markdown Text with two trailing spaces (on the right) can be used for things like poems ``` 行尾两个空格是 Markdown 的硬换行符，`test.md` 用它演示“逐行各自成句”的诗歌排版场景，验证文法是按“行”而非“段落”来处理尾随空格的。 ### 2.11 水平分割线：三种写法 ```markdown * * * * **** -------------------------- ``` 空格分隔的星号、连续星号、连续连字符三种形态全部覆盖，验证它们被统一识别为分割线而不是列表或下划线标题。 ### 2.12 图片 ```markdown picture alt ``` 带 alt 文本与可选 title 的标准图片语法，属于 `meta.image` 家族 scope。 ### 2.13 Markdown Extra：表格、定义列表与缩写 ```markdown | Header | Header | Right | | ------ | ------ | -----: | | Cell | Cell | $10 | | Cell | Cell | $20 | * Outer pipes on tables are optional * Colon used for alignment (right versus left) ``` 表格（GFM/Markdown Extra 扩展）：表头、对齐行、数据行一应俱全，`-----:` 冒号在右表示右对齐；注释明确说明“表格外围竖线可选、冒号用于控制对齐”。 ```markdown Bottled water : $ 1.25 : $ 1.55 (Large) Milk Pop : $ 1.75 ``` 定义列表：术语后跟 `: 定义` 缩进行，一个术语可对应多个定义，多个术语可共享同一个定义。 ```markdown *[ABBR]: Markdown plus abbreviations (produces an <abbr> tag) ``` 缩略语（abbreviation）声明行，编译为 `<abbr>` 标签。这三段把 Markdown Extra 扩展语法完整覆盖在内，说明 `test.md` 面向的语法模型是“CommonMark 核心 + GitHub/Markdown Extra 扩展”的超集。 ## 三、从基线 JSON 看 scope 与主题颜色的映射 [colorize-results/test_md.json](https://link.gitcode.com/i/f504606896e216712ac99944261f97b9) 是 `test.md` 的 TextMate 分词基线，共 3768 行，对源文件**逐字符**记录了三元组：字符 `c`、scope 串 `t`、各主题颜色 `r`。下表整理了本文涉及的核心映射（色值为基线中实际记录的十六进制）： | Markdown 构件 | 代表性 scope 串 | dark_plus | light_plus | hc_black | hc_light | | --- | --- | --- | --- | --- | --- | | ATX 标题 `#` | `markup.heading.markdown heading.1.markdown punctuation.definition.heading.markdown` | `#569CD6` | `#800000` | `#6796E6` | `#0F4A85` | | 标题文本 | `entity.name.section.markdown` | `#569CD6` | `#800000` | `#6796E6` | `#0F4A85` | | 粗体 `**` | `markup.bold.markdown` | `#569CD6` | `#000080` | `#569CD6` | `#000080` | | 斜体 `_` | `markup.italic.markdown` | `#C586C0` | `#800080` | `#C586C0` | `#800080` | | 无序列表符号 | `markup.list.unnumbered.markdown punctuation.definition.list.begin.markdown` | `#6796E6` | `#0451A5` | `#6796E6` | `#0451A5` | | 块引用 `>` | `markup.quote.markdown punctuation.definition.quote.begin.markdown` | 跟随 quote 主题 | — | — | — | | 围栏代码块 | `markup.fenced_code.block.markdown` | 代码块主题 | — | — | — | | 内嵌 HTML 字符串 | `string.quoted.double.html` | `#0000FF` | `#0000FF` | `#0000FF` | `#0F4A85` | | HTML 标签标点 | `punctuation.definition.tag` | `#808080` | `#800000` | `#808080` | `#0F4A85` | 基线同时记录了 8 套主题：`dark_plus`、`light_plus`、`dark_vs`、`light_vs`、`hc_black`（高对比黑）、`hc_light`（高对比白）、`dark_modern`、`light_modern`。从数据可以看到，`dark_plus`、`dark_vs`、`dark_modern` 在多数规则上色值一致，而高对比主题（`hc_black`/`hc_light`）会专门调整明度以保证可读性。同一目录下的 [colorize-tree-sitter-results/test_md.json](https://link.gitcode.com/i/0f1a1108e389df8671f389b93d1edf5c) 则是 Tree-sitter 引擎对同一份样本的输出基线，二者共同构成双引擎回归的“黄金快照”。 ## 四、Colorize 回归测试的运行机制 `test.md` 不是孤立文件，它是 [colorizer.test.ts](https://link.gitcode.com/i/6c01b6e673f89571dab70148860e209c) 驱动的自动化测试样本之一。测试的核心逻辑可以概括为三步： 1. **遍历样本**：测试套件 `suite('colorization')` 通过 `fs.readdirSync(fixturesPath)` 枚举 `colorize-fixtures` 目录下的**所有文件**，每个文件生成一个 `colorize: <fixture>` 用例（见 [colorizer.test.ts](https://link.gitcode.com/i/6c01b6e673f89571dab70148860e209c#L89-L95)），因此新增一个夹具文件就等于新增一组回归测试。 2. **双引擎捕获**：对每个样本，同时调用 `_workbench.captureSyntaxTokens`（TextMate 引擎）与 `_workbench.captureTreeSitterSyntaxTokens`（Tree-sitter 引擎）两条内部命令，把分词结果序列化为 JSON（见 [colorizer.test.ts](https://link.gitcode.com/i/6c01b6e673f89571dab70148860e209c#L12-L18)）。 3. **快照比对**：结果与 `colorize-results` / `colorize-tree-sitter-results` 目录下已有的基线 JSON 做 `assert.deepStrictEqual` 逐字符比对；若基线不存在则直接写入生成；若存在差异，则用 `hasThemeChange` 检查**颜色是否真的发生变化**——只有当 token 类型或主题颜色都变化时才判定失败，“变了但颜色一致”的情况被容忍（见 [colorizer.test.ts](https://link.gitcode.com/i/6c01b6e673f89571dab70148860e209c#L23-L45)）。也就是说，这份测试守护的是“**编辑器里看到的颜色不变**”这一用户可感知契约，而不是死板地锁定内部 token 细节。 测试还通过 `editor.experimental.preferTreeSitter.*` 配置（针对 typescript、ini、regex、css）显式开启 Tree-sitter 路径，并在 `suiteTeardown` 中还原配置（见 [colorizer.test.ts](https://link.gitcode.com/i/6c01b6e673f89571dab70148860e209c#L70-L87)），保证测试环境可重复、不留副作用。 ## 五、语法定义与语言配置：着色的“宪法” `test.md` 验证的 scope 全部来自 Markdown 的 TextMate 文法定义，它由内置扩展 [markdown-basics](https://link.gitcode.com/i/bd7f483fdeb335640a05c853406f267a) 提供。该扩展在 `contributes` 中声明了 `markdown` 语言 id，绑定 `.md`、`.markdown`、`.mdown`、`.mdtext`、`.workbook` 等扩展名，并将语法文件指向 `./syntaxes/markdown.tmLanguage.json`，根 scope 为 `text.html.markdown`——这正是基线 JSON 中每个 token scope 串的前缀来源。 更关键的是 `embeddedLanguages` 映射：它声明了 Markdown 内部可以嵌入哪些语言，例如 `meta.embedded.block.html` → `html`、`meta.embedded.block.css` → `css`、`meta.embedded.block.javascript` → `javascript`、`meta.embedded.block.yaml` → `yaml`，以及 java、python、rust、shellscript、typescript 等数十种。这就是 `test.md` 中 `<script>`、`<style>` 内部代码能按各自语言着色的原因。此外 `unbalancedBracketScopes` 声明链接与列表标点不计入括号配对，避免 Markdown 标点干扰括号着色。 配套的 [language-configuration.json](https://link.gitcode.com/i/5ebc628b8bcd972a6a7f8b00bf37806e) 定义了编辑体验层面的规则：`<!--` / `-->` 块注释、`{}[]()` 括号配对、`folding` 的 `<!-- #region -->` 折叠标记，以及面向 Unicode 的 `wordPattern`——这些虽不直接决定颜色，但与高亮同属“语言支持”的完整闭环。 ## 六、同目录其他夹具：边界场景的补充证据 `colorize-fixtures` 目录内还沉淀了大量历史回归样本，与 `test.md` 互为补充： - [md-math.md](https://link.gitcode.com/i/220ba81c804e22fc3e47ca901de34b7d)：专测数学公式块（`$$` / `$`），包括行内公式、公式内注释、缩进代码块与注释中禁用公式、`\text{...}` 两种写法、以及金额 `$10 $20` 不得被误判为公式等十余种边界； - [test-33886.md](https://link.gitcode.com/i/637cd5232116c4063ae615f266b58598)：验证 `<pre><code>` 包裹的 HTML 代码块内部内容**不得**被解析为 Markdown 标题，是“HTML 块内禁用 Markdown 解析”的典型回归； - 其余如 `test-embedding.html`（HTML 多语言嵌入）、`test-brackets.tsx`、`test-issue*.ts` 等，分别守护各自语言的着色边界。 这些样本的存在说明：高亮引擎的每一次文法修订，都必须让“历史样本快照 + 新样本快照”全部通过，`test.md` 正是这套体系中最全面的一份 Markdown 语法字典。 ## 七、小结：如何用好这份夹具 `test.md` 的价值有三层：对**普通用户**，它是检验 openvscode-server Markdown 高亮完整度的“语法体检表”——打开该文件即可肉眼核对标题、列表、代码块、表格等所有规则是否正常渲染；对**扩展开发者**，它是编写或调试 `markdown.tmLanguage.json` 时最直接的参考样本与复现用例；对**引擎维护者**，它是 colorize 回归测试的固定输入，任何分词行为的漂移都会在 `test_md.json` / `colorize-tree-sitter-results/test_md.json` 的快照比对中暴露。理解这份文件，就等于理解了 Markdown 高亮从“文本 → scope → 主题颜色”的完整数据链路。

• 开发工具
• IDE
• 代码编辑器
• 后端