企业官网建设流程全解析

• 文档
• 开发工具
• CLI

导读

本文以 pandoc 官方回归测试用例 test/command/8003.md 为切入点，深入剖析ascii_identifiers这一 Markdown 语法扩展：它能让 pandoc 在自动生成标题锚点（HTMLid）时，把带变音符号、非拉丁字母的标题文本转写为纯 ASCII 形式。读完本文，你将理解该扩展的开启方式、与auto_identifiers/gfm_auto_identifiers的依赖关系，以及其底层基于 Unicode NFD 规范化的实现原理，并能在自己的文档流水线中复现与验证这一行为。

一、从一个回归测试用例说起

仓库中的 test/command/8003.md 是一份非常精简但信息量完整的命令行测试，其完整内容如下：

% pandoc -f markdown+ascii_identifiers # Işık ^D <h1 id="isik">Işık</h1>

逐行解读这份测试：

• % pandoc -f markdown+ascii_identifiers：以markdown为输入格式，并通过+ascii_identifiers显式开启名为ascii_identifiers的语法扩展；
• # Işık：输入一个 ATX 一级标题，标题文本是土耳其语单词 “Işık”（意为“光”），其中同时包含带软音符的ş（U+015F）和“无点 i”ı（U+0131，注意它不是普通拉丁字母i）；
• ^D：表示在此输入 EOF，结束标准输入；
• <h1 id="isik">Işık</h1>：期望输出。标题正文保持原样Işık，但自动生成的 HTML 锚点id被转写为纯 ASCII 的isik——ş变成了s，无点ı变成了普通i。

这个用例在命令测试体系（test/command/8003.md 这类文件由 test/Tests/Command.hs 驱动）中充当回归保护：它确保此后任何改动都不会破坏ascii_identifiers的转写结果。这也说明该功能是一个被官方测试固定下来的稳定行为。

二、扩展的定位：定义、默认值与依赖关系

在 pandoc 的扩展体系中，ascii_identifiers在 src/Text/Pandoc/Extensions.hs 中定义：

| Ext_ascii_identifiers -- ^ ascii-only identifiers for headers; -- presupposes Ext_auto_identifiers

从定义注释可以提炼出三个关键事实：

1. 该扩展的作用是“为标题生成纯 ASCII 标识符（id）”；
2. 它预先假定（presupposes）Ext_auto_identifiers被开启——也就是说，它本身不负责“生成”标识符，而是负责把已生成的标识符“ASCII 化”。在默认的markdown输入格式中，auto_identifiers默认开启，因此该前提通常自然满足；只有当你在自定义扩展集时显式关闭了auto_identifiers，ascii_identifiers才会失去作用对象。
3. 在 src/Text/Pandoc/Extensions.hs 的默认扩展表中，Ext_ascii_identifiers默认是关闭的（默认标记为off），需要像测试用例那样用+ascii_identifiers显式启用；用-ascii_identifiers也可以从已开启的扩展集中移除它。

用命令行启用/禁用：

# 显式开启 pandoc -f markdown+ascii_identifiers input.md -o output.html # 从默认扩展集中移除 pandoc -f markdown-ascii_identifiers input.md -o output.html

三、底层实现：标识符生成管线的两段式改造

要理解ascii_identifiers究竟改动了什么，需要先看 pandoc 生成标题标识符的完整管线。核心实现在 src/Text/Pandoc/Shared.hs 中：

-- | Convert Pandoc inline list to plain text identifier. inlineListToIdentifier :: Extensions -> [Inline] -> T.Text inlineListToIdentifier exts = textToIdentifier exts . stringifyInlines . unEmojify where ... -- | Convert string to plain text identifier. textToIdentifier :: Extensions -> T.Text -> T.Text textToIdentifier exts = dropNonLetter . filterAscii . toIdent where filterAscii | extensionEnabled Ext_ascii_identifiers exts = toAsciiText | otherwise = id toIdent | extensionEnabled Ext_gfm_auto_identifiers exts = filterPunct . spaceToDash . T.toLower | otherwise = T.intercalate "-" . T.words . filterPunct . T.toLower

可以看到filterAscii这一步：当Ext_ascii_identifiers开启时，在完成小写化、标点过滤、空格转连字符等常规处理之后，会额外施加一个toAsciiText变换。也就是说，ASCII 化发生在标识符生成的最后阶段，作用在已经规范化（小写、去标点）的文本之上。

标识符最终通过uniqueIdent（src/Text/Pandoc/Shared.hs）保证唯一性：若生成的 id 与已使用集合冲突，会自动追加-1、-2等后缀，最多尝试到 60000；若标题文本转写后为空字符串，则退化为section。

四、核心引擎：Text.Pandoc.Asciify 的 NFD 转写原理

toAsciiText的实现位于独立的 src/Text/Pandoc/Asciify.hs，该模块的职责注释写得很清楚：“把带重音的拉丁字母转换为对应的无重音 ASCII 等价物（用于构造 HTML 标识符）”。其核心实现如下：

toAsciiText :: Text -> Text toAsciiText = T.filter isAscii . T.map specialCase . TN.normalize (TN.NFD) where specialCase '\x131' = 'i' -- Turkish undotted i specialCase c = c

逐层拆解这条处理链（从右往左执行）：

1. NFD 规范化（TN.normalize (TN.NFD)）：把每个字符规范分解为“基本字母 + 组合变音记号”。例如带软音符的ş（U+015F）被分解为s（U+0073）+ 组合软音符（U+0327）；
2. 特殊映射（T.map specialCase）：针对无法通过分解解决的字符做手工映射，目前唯一特例是土耳其语“无点 i”ı（U+0131），它被直接映射为普通 ASCIIi；
3. 过滤（T.filter isAscii）：丢掉所有非 ASCII 字符。由于组合变音记号（如 U+0327）都是非 ASCII 码点，经过 NFD 分解后它们会在这一步被清除，剩下干净的纯 ASCII 基本字母。

同样地，toAsciiChar实现了单字符版本：先 NFD 分解，若首个码点是 ASCII 且后续全是组合标记（isMark），则返回该基本字母，否则返回Nothing。这套“分解 + 过滤”的组合拳，就是Işık → isik的完整机理：ş分解后留下s，ı经特殊映射变为i，最终ışık被转写为isik。

五、集成点：标题注册时的二次转换

上述管线在哪里被真正调用？答案在 src/Text/Pandoc/Parsing/General.hs 的registerHeader函数中。当标题没有显式指定id且auto_identifiers开启时：

let id' = uniqueIdent exts (B.toList header') ids let id'' = if Ext_ascii_identifiers `extensionEnabled` exts then toAsciiText id' else id'

这段代码揭示了一个容易被忽略的细节：ascii_identifiers并非简单替换uniqueIdent的输出，而是在其基础上再做一次toAsciiText二次转换，并且同时把id'与id''都记入已用标识符集合。这种设计有两个好处：

• 二次转换复用uniqueIdent的唯一性保证（连字符、后缀编号逻辑不受影响）；
• 同时登记两个标识符，可以避免出现“ASCII 化后撞车”的边界情况，例如标题Café与Cafe在 ASCII 化后都会得到cafe，此时第二个标题会被唯一性机制改写为cafe-1。

registerHeader同时还负责处理显式id冲突：遇到重复的显式标识符会通过logMessage $ DuplicateIdentifier ident pos发出DuplicateIdentifier警告。

六、与 gfm_auto_identifiers 的叠加行为

ascii_identifiers并非只适用于传统的auto_identifiers。当 GitHub 风格的gfm_auto_identifiers也被开启时，两者可以叠加。这在 CommonMark 阅读器的扩展配置中得到了显式处理，见 src/Text/Pandoc/Readers/CommonMark.hs：

[ (autoIdentifiersSpec <>) | isEnabled Ext_gfm_auto_identifiers opts , not (isEnabled Ext_ascii_identifiers opts) ] ++ [ (autoIdentifiersAsciiSpec <>) | isEnabled Ext_gfm_auto_identifiers opts , isEnabled Ext_ascii_identifiers opts ] ++

也就是说：在gfm_auto_identifiers开启的前提下，若未开启ascii_identifiers，使用普通的autoIdentifiersSpec规则；若两者同时开启，则切换为autoIdentifiersAsciiSpec规则。两种规则的差异还体现在 src/Text/Pandoc/Shared.hs 的细节上：gfm_auto_identifiers模式下dropNonLetter保持原样（不再丢弃前导非字母），并允许更多标点类别（如连字符、下划线、各类组合记号与连接标点），而ascii_identifiers的filterAscii仍然作为最终一道关卡把关。

一个值得注意的连带效应：开启ascii_identifiers时，src/Text/Pandoc/Shared.hs 中inlineListToIdentifier的unEmojify也会被激活——即先把 emoji 替换为其别名文本再参与转写，这与gfm_auto_identifiers的行为保持一致。

七、实战验证：复现测试并对比默认行为

你可以直接用终端复现 test/command/8003.md 的测试（本仓库即 pandoc 源码，构建后可运行）：

printf '# Işık\n' | pandoc -f markdown+ascii_identifiers

期望输出：

<h1 id="isik">Işık</h1>

为观察该扩展的实际作用，建议对比关闭它时的默认行为：

printf '# Işık\n' | pandoc -f markdown

此时由于未做 ASCII 化，自动生成的标识符会保留转写后的小写 Unicode 字符（ışık形式），与+ascii_identifiers得到的isik形成鲜明对照。这正是该扩展的典型应用场景：当你的文档需要稳定的纯 ASCII 锚点以兼容旧版浏览器、URL 链接约定或下游系统对标识符字符集的限制时，开启ascii_identifiers可确保#isik这类链接在任何环境下都稳定可达，而不会因编码问题失效。

八、小结与注意事项

• 启用方式：-f markdown+ascii_identifiers（或对任意默认含该扩展的格式使用-ascii_identifiers关闭）；默认情况下该扩展处于关闭状态。
• 依赖前提：它以auto_identifiers（自动标识符生成）为前提；若标题本身带有显式id，则ascii_identifiers不会改写显式 id，仅作用于自动生成的 id。
• 转写机理：基于 Unicode NFD 规范分解 + 土耳其语无点 i 特殊映射 + ASCII 过滤，实现在 src/Text/Pandoc/Asciify.hs。
• 唯一性保障：ASCII 化前后两个标识符都会被登记，避免多标题转写后冲突；空结果回退为section，冲突时追加数字后缀（见 src/Text/Pandoc/Shared.hs）。
• 回归保障：本行为由 test/command/8003.md 这一官方命令测试长期守护。

对于面向多语言内容的文档工程，ascii_identifiers是一个“小而关键”的开关：它只改动锚点、不动正文，却能让 URL 引用在多语言环境下保持长期稳定。

• 文档
• 开发工具
• CLI