企业官网建设流程全解析

• 开发工具
• CLI

导读：本文以 Universal Ctags 仓库中Units/parser-markdown.r/yaml-in-code-block.d测试用例为主线，完整剖析 Markdown 解析器如何识别围栏代码块、如何把代码块内容"外包"给对应语言解析器（guest parser）生成跨语言标签，以及 YAML frontmatter 与 guest 标签输出背后的 promise 与 extra 机制。读完本文，你将掌握--extras=+{guest}、--fields=+{language}{end}等选项的实际效果，并能读懂.d测试目录中 input/args/expected 三件套的运作方式。

一、测试用例全景：yaml-in-code-block.d 在测什么

Units/parser-markdown.r/yaml-in-code-block.d/是一个典型的 ctags 单元测试目录，由四个文件组成：

README记录该用例取自 Universal ctags 的 issue #2965，由 @rickalex21 提交，核心诉求是：当 YAML 代码块出现在 Markdown 文档中时，ctags 应能像解析普通 YAML 文件一样为代码块内的内容生成标签。

测试输入input.md的结构如下：

I will be capturing these animal tags with ```--_mtable-regex```. ```yaml --- title: "Animals" date: 2021-04-17T14:22:02-05:00 draft: false tags: ['dog','cat','bear','lion','monkey','tiger','dolphin','elephant','whale'] ---

Mline

cat <<EOF --------- EOF hello() { echo "hello" }

Mline2

文档包含三块内容：一个正文段落、一个 `yaml` 围栏代码块、一个 `sh` 围栏代码块，以及两个 `###` 三级标题（Mline、Mline2）与一条 `---` 分隔线。测试的关键在于：**YAML 代码块中的内容属于 YAML 语法，不属于 Markdown 语法**，因此需要由 YAML 解析器以 guest 身份接管这部分输入。 ## 二、三件套的运作方式：input、args、expected 如何协同 ctags 单元测试框架（详见 [docs/testing-ctags.rst](https://link.gitcode.com/i/8204c198904768a4ca7bbc074f636d50)）约定：每个 `.d` 目录中，`input.*` 是输入源文件，`args.ctags` 存放要附加的选项，`expected.tags` 存放期望输出。运行测试时，ctags 以 `args.ctags` 中的选项处理 `input.md`，再把实际输出与 `expected.tags` 逐行比对。 `yaml-in-code-block.d/args.ctags` 只有三行选项，却决定了整个测试的输出形态： ```text --sort=no --extras=+{guest} --fields=+{language}{end}

• --sort=no：关闭标签按名称排序，让标签保持输入文件中出现的先后顺序，便于与expected.tags逐行对照；
• --extras=+{guest}：启用guest扩展——这是本文的核心，它允许 ctags 在某个文件里用"其他语言"的解析器生成标签（详见下文）；
• --fields=+{language}{end}：为每条标签额外输出language（标签所属语言）与end（标签作用域结束行号）两个字段。

对应的期望输出expected.tags：

Mline input.md /^### Mline$/;" S language:Markdown end:25 Mline2 input.md /^### Mline2$/;" S language:Markdown end:26 EOF input.md /^cat <<EOF$/;" h language:Sh end:19 hello input.md /^hello()$/;" f language:Sh

四条标签分属两个语言：Mline、Mline2是 Markdown 的S（subsection，三级标题）标签；EOF、hello是 Sh（shell）解析器以 guest 身份从sh代码块里提取的标签——EOF是 heredoc 标签（h类型），hello是函数标签（f类型）。

这里有一个值得注意的细节：YAML 代码块本身没有产生任何标签。原因在于该代码块内只有 YAML 的 frontmatter 结构（title:、date:、draft:、tags:等键），这些内容对 YAML 解析器而言属于数据而非命名对象；而 shell 代码块中的 heredoc 标签名EOF与函数hello则是真实可索引对象，因此被 Sh 解析器输出。对比Units/parser-markdown.r/frontmatter.d用例可以看到，当 YAML frontmatter 出现在文件头部（而非围栏代码块内）时，title:键会被提取为t类型标签（Python标签，见 expected.tags）。

三、核心机制一：围栏代码块与 promise（Promise）

3.1 解析器如何识别围栏代码块

Markdown 解析器的主循环实现在 parsers/markdown.c 的findMarkdownTags()函数中（L352-L532）。它逐行读取输入，用inCodeChar状态机跟踪围栏代码块：

• 当一行以`或~开头且连续相同字符数nSame >= 3时，判定为围栏代码块开始/结束（L402-L445）；
• 代码块起始行上，围栏之后的文本被当作语言标记langMarker，例如``yaml中的 `yaml`、``sh中的sh；
• 代码块内部的行一律lineProcessed = true，不会被当作 Markdown 标题、hashtag 或 footnote 处理（L464-L466）。

也就是说，代码块中的hello()不会被误判为 Markdown 文本，这正是"代码块属于其他语言"这一语义在解析层面的落地。

3.2 makePromise：把代码块"外包"给子解析器

识别出代码块后，解析器并不直接解析代码内容，而是调用makePromise()登记一个"承诺"（promise），把该行区间的输入转交给以代码块语言命名的解析器处理（L431-L435）：

if (vStringLength (codeLang) > 0 && startLineNumber < endLineNumber) makePromise (vStringValue (codeLang), startLineNumber, 0, endLineNumber, 0, startSourceLineNumber);

makePromise()在 main/promise.c（L65-L136）中实现，参数依次是：目标解析器语言名、起始行/列、结束行/列、源文件行偏移。核心逻辑包括：

• 将语言名解析为langType，语言不存在则返回-1（放弃该 promise）；
• 如果guestextra 未启用，非 thin 区域（即普通行区间）的 promise 会被直接拒绝（L89-L91）——这正是--extras=+{guest}必须出现的原因；
• promise 对象被压入全局 promise 栈，支持嵌套（parent_promise字段），多个代码块可以排队等待后续处理。

从源码结构可以推断，promise 队列在输入文件解析完成（或forcePromises()被调用）后被逐一"兑现"：对应语言的解析器在指定的行区间上重新运行，其产物作为 guest 标签合并进输出。main/parse.c中的forcePromises()、breakPromisesAfter()（L4494-L4545）负责这批 promise 的调度与生命周期管理。

四、核心机制二：guest extra 与 guest 标签

4.1 guest extra 的定义

guest是 ctags 内置的一个 extra（附加输出开关），定义在 main/xtag.c（L74-L75）：

{ false, 'g', "guest", "Include tags generated by guest parsers"},

• 短名：g，所以--extras=+g与--extras=+{guest}等价（Units/parser-markdown.r/c-guest.d/args.ctags用的就是+g）；
• 默认关闭（第一字段为false），必须显式启用；
• 枚举定义在 main/xtag.h（XTAG_GUEST，L33），并保留旧名XTAG_TAGS_GENERATED_BY_GUEST_PARSERS以兼容 Geany 等下游使用者。

4.2 什么时候一条标签会被标记为 guest

在 main/entry.c 的initTagEntry()中（L2102-L2105）：

if (isAreaStacked ()) markTagExtraBit (e, XTAG_GUEST); if (doesSubparserRun ()) markTagExtraBit (e, XTAG_SUBPARSER);

只要标签生成时输入流处于"区域栈"（area stack）状态——即由 promise 提供的受限区间——该标签就被自动标记XTAG_GUEST。因此：

• 默认情况下（未启用guestextra），promise 在 main/promise.c 的makePromise()处就被拦截（L89-L91），根本不会运行对应语言的解析器，代码块内自然无标签输出；
• 启用guest后，promise 得以兑现，代码块内产生的标签全部带有 guest 属性，并在输出中附带language:Sh之类的字段（由--fields=+{language}控制显示）。

4.3 guest 与 subparser 的区分

需要澄清一个常见混淆：guest 与 subparser 是两个不同的扩展机制，但常常协同工作。initTagEntry()中两者分别用独立的 extra 位标记：

• guest（XTAG_GUEST）：表示标签来自输入文件中的一段"外来区域"（如 Markdown 中的代码块），由 promise 驱动，是本文测试用例使用的机制；
• subparser（XTAG_SUBPARSER）：表示标签由某个语言的子解析器（subparser）生成，例如 C++ 的cxx解析器之于 C 解析器。

Markdown 解析器同样定义了 subparser 接口（markdownSubparser，见 parsers/markdown.c 的extractLanguageForCodeBlock()/notifyCodeBlockLine()，L218-L263），允许第三方解析器声明"我能识别 Markdown 代码块中的语言标记"，从而在代码块内运行。packcc 解析器即以此方式在 Markdown 代码块内运行（见 packcc-parser-running-within-code-block.d，其args.ctags同时使用了--languages=+TOML与--extras=+g）。

五、纵深：Markdown 代码块与 Frontmatter 的联动

虽然yaml-in-code-block.d中 YAML 代码块未产出标签，但它触及了 ctags 处理 Markdown+YAML 的完整生态：frontmatter 解析链。

Markdown 解析器在文件首行检测---起始的 frontmatter 区域（L378-L400），并通过makePromise("FrontMatter", ...)把该区域交给 FrontMatter 解析器（L390-L391）。FrontMatter 解析器（parsers/frontmatter.c）再为内部的 YAML 部分创建makePromise("YamlFrontMatter", ...)（L58-L59），YamlFrontMatter 解析器（parsers/yamlfrontmatter.c）作为 Yaml 解析器的 subparser，通过ypathTables中的title路径把title:键提取为 FrontMatter 语言的t类型标签（L49-L55）。

这条"Markdown → FrontMatter → YamlFrontMatter → Yaml"的三级嵌套链，在 parsers/markdown.c 的MarkdownParser()定义中有明确注释（L552-L564）：由于 subparser 对内存输入流的要求无法向上传播，Markdown 解析器被迫设置def->useMemoryStreamInput = true才能支撑这一堆叠结构。该细节解释了为何 frontmatter 用例（frontmatter.d）能在--extras=+g下输出Python这样的t标签，而 yaml-in-code-block 用例中的 YAML 块由于只有 frontmatter 数据键、没有命名对象，所以不产生标签——两者机制相同，差异在输入内容本身。

六、动手验证：在本地复现该测试用例

仓库是只读的，但你可以用已构建的 ctags 可执行文件自行验证（构建方式参见 docs/building.rst）：

# 进入测试目录（仅用于说明路径，命令在仓库根目录执行） ctags --options=NONE \ --sort=no \ --extras=+{guest} \ --fields=+{language}{end} \ -o - Units/parser-markdown.r/yaml-in-code-block.d/input.md

预期输出与expected.tags一致：两条language:Markdown的S标签、两条language:Sh的 guest 标签（h类型EOF与f类型hello），其中Mline的end:25来自标题作用域在文件末尾（L26）被关闭（fillEndField()，见 parsers/markdown.c 与 L528-L531）。

你可以通过以下实验加深理解：

1. 去掉--extras=+{guest}：EOF、hello两条标签消失——promise 在makePromise()处被 guest extra 门控拦截；
2. 把sh块改为yaml块：Sh 标签消失，YAML 块仍无标签（数据键不生成标签）；
3. 去掉--sort=no：输出顺序改变，无法与expected.tags直接对照——这也是测试固定使用--sort=no的原因。

七、小结

yaml-in-code-block.d虽然只是一个 26 行的测试输入，却浓缩了 ctags Markdown 解析器的三大核心机制：

• 围栏代码块识别：findMarkdownTags()用状态机区分 Markdown 语法与代码块，代码块内容绝不参与 Markdown 标签生成；
• promise 机制：makePromise()把代码块行区间"外包"给对应语言解析器，并由guestextra 控制开关；
• guest 标签：区域栈（area stack）驱动的标签自动打上XTAG_GUEST标记，输出中可用language字段区分来源语言。

对于文档站、博客等大量使用 Markdown + 内嵌代码块的场景，这套机制让 ctags 一次扫描即可同时索引 Markdown 结构（标题、章节）与内嵌代码（shell 函数、C 函数等），是理解 ctags 多语言混合索引能力的绝佳入口。相关用例还可在 c-guest.d、frontmatter.d 与 packcc-parser-running-within-code-block.d 中继续延伸阅读。

• 开发工具
• CLI