开发工具格式化CLI【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址https://gitcode.com/gh_mirrors/pr/prettier点击查看免费下载导读本文以 Prettier 仓库中的格式测试用例 encoded-greater-than.md 为切入点深入剖析 Prettier 在proseWrap: always模式下如何格式化 Markdown 引用块blockquote重点揭示六种 HTML 实体编码形式的大于号如何在行合并过程中被准确识别、正确保留避免被误判为引用块标记而丢失。读完本文你将掌握 Prettier Markdown 格式化器对 blockquote 标记的底层识别规则、proseWrap三种模式的差异以及原始文本raw与解码文本value这一核心设计取舍并能自行复现与验证相关行为。一、测试用例定位它在验证什么在 Prettier 仓库中tests/format/markdown/blockquote/prose-wrap-always/目录专门用于验证 Markdown 引用块在proseWrap: always模式下的格式化行为其中包含五个相互补充的用例文件encoded-greater-than.md本文主体验证以 HTML 实体形式编码的大于号encoded-newline.md验证编码换行符#10;、#xA;、NewLine;与引用块的交互escaped-greater-than.md验证反斜杠转义的大于号\indented-greater-than.md验证空格/Tab 缩进后的标记issue-19528.md验证test\这类文字紧跟转义大于号的场景对应历史 issue。该目录下的测试入口 format.test.js 仅一行核心调用runFormatTest(import.meta, [markdown], { proseWrap: always });它把同一目录下所有.md文件作为输入用markdown解析器配合proseWrap: always选项执行格式化并将输出与snapshots/format.test.js.snap 中的快照比对。换句话说这组测试是 Prettier 官方对引用块 实体编码字符 强制换行组合行为的行为规范定义任何格式化改动若导致快照不符即视为回归。二、用例输入全解六种大于号编码形式原文档 encoded-greater-than.md 全文共 17 行由 6 个结构完全相同的段落组成每段两行引用文本 a gt; b a #62; b a #x3e; b a GT; b a #062; b a #x3E; b每一段的第一行都是字面嵌套引用 a外层标记 内层嵌套标记第二行则是外层标记 一个以 HTML 实体编码形式出现的 普通文本b。六种编码形式覆盖了 HTML 字符引用规范的主要写法编码形式类型对应字符gt;小写命名实体GT;大写命名实体#62;十进制数字引用#062;十进制数字引用带前导零#x3e;十六进制数字引用小写#x3E;十六进制数字引用大写该用例刻意穷举这些变体是为了验证无论用户以哪种合法形式书写 HTML 实体Prettier 都必须一视同仁地正确处理。三、期望输出换行合并与实体保留对应的快照见 format.test.js.snap记录了格式化后的期望结果以第一段为例 a gt; b全部六个段落格式化后分别得到 a gt; b a #62; b a #x3e; b a GT; b a #062; b a #x3E; b从这个输出可以读出三条明确的行为约定行合并原本各占一行的两段引用内容 a与gt; b被合并进同一行中间以单个空格衔接——这正是proseWrap: always若超出打印宽度则换行在内容未超宽时表现出的优先压缩为一行特性实体原样保留内容中的gt;、#62;等实体编码不会被解码成字面而是以原始形态原封不动地输出嵌套结构不被破坏输出行的 前缀保持外层标记 内层嵌套标记的结构说明格式化器对引用深度blockquote 嵌套层级的判断是准确的。四、proseWrap 选项三种模式与默认值要理解上述行为先要明确proseWrap选项本身。该选项定义在 common-options.evaluate.js属于通用选项Markdown 语言通过 language-markdown/options.js 直接引用它取值类型默认值行为alwayschoice否文本超出打印宽度默认printWidth: 80时换行否则合并为一行neverchoice否绝不主动换行保持单行preservechoice是按原样保留已有的换行默认值为preserve即默认不干预原文的换行布局。always是三个取值中介入最深的模式本文全部示例均基于该模式。从 mdast.js 的definition打印分支还可以看到proseWrap always时链接定义中使用的分隔符是line可换行空格而其他模式下是普通空格说明该选项的影响面覆盖了行内空白与链接定义等多个层面。五、源码机制一blockquote 的打印模型Prettier 将 Markdown 解析为 mdast 抽象语法树blockquote节点的打印逻辑位于 mdast.jscase blockquote: return [ , align( , printChildren(path, options, print))];这条语句揭示了两层关键设计前缀统一化无论源码中 blockquote 标记原本是、还是带缩进的输出时一律重新生成标准前缀 对齐align( , ...)让嵌套内容中每一个换行处都自动补上相同深度的前缀从而保证多行引用块的纵向对齐。换言之每一行引用内容以开头这件事在打印阶段是由代码统一负责的而不是直接照抄原文。这引出一个重要推论原始行中的引用标记必须先在某个阶段被剥离干净否则会被当作内容重复输出。这个阶段就是下文要讲的预处理。六、源码机制二预处理中的 raw 与 value 取舍剥离标记发生在打印前的 AST 预处理阶段入口位于 print/preprocess.js。其中有一段非常重要的注释第 181-183 行Usingnode.raw, we can better preserve the original text, especially escaped characters. Usingnode.value, we dont need to care about markers like\n inblockquotes.这里点出了 mdast 文本节点的双重表示node.value解码后的文本HTML 实体已还原为字符gt;→便于语义判断node.raw原始文本保留用户书写的实体、转义等一切细节便于原样输出。Prettier 选择了raw作为文本重排的基底let text node.raw这正是实体不被解码、原样保留这一行为的最直接来源。但raw的代价是它可能包含\n 这类夹带在原文中的引用块标记。因此当某个文本节点位于 blockquote 内部时第 197-203 行预处理会调用 getBlockquoteRawText.js 中的getBlockquoteRawText(text, node)把混入 raw 文本的标记精确剥离。七、源码机制三getBlockquoteRawText 的核心算法getBlockquoteRawText是理解整个用例的钥匙其算法分三步见 get-blockquote-raw-text.js1. 识别一切合法标记形态的正则const rawBlockquoteRegexp /[ \t]*(?:|\\|gt;|GT;|#0*62;|#[xX]0*3[eE];)[ \t]*/y;这是一个 stickyy标志正则从指定位置开始连续匹配。它显式枚举了会被当作引用块标记的形态正则分支匹配内容对应本文用例字面大于号第一行 a中的标记\\反斜杠转义大于号对应escaped-greater-than.mdgt;/GT;大小写命名实体用例第 1、4 段#0*62;十进制数字引用允许前导零用例第 2、5 段#[xX]0*3[eE];十六进制引用x/X、3e/3E、前导零均容错用例第 3、6 段六种实体写法在此全部被覆盖与测试输入一一对应这正是任意合法编码形式都能被正确识别的底层保证。2. 统计解码后内容中的引用深度function countValueLeadingGreaterThan(line) { let count 0; for (const character of line) { if (character ) count; else if (character ! character ! \t) break; } return count; }该函数以解码后的 value 行为输入统计其行首连续出现的数量。由于所有实体在 value 中都已还原为字面六种写法统计结果一致。这个数字代表当前行在内容语义上保有的引用深度。3. 剥离标记、保留内容function removeBlockquoteMarkers(line, greaterThanToKeep) { // 用 sticky 正则扫描收集所有形似标记的匹配位置 // greaterThanToKeep 0 时剥离全部标记 // 否则保留最右侧的 greaterThanToKeep 个匹配剥离开头部分 }这里体现了最精妙的设计rawBlockquoteRegexp会把行内任何位置的实体包括内容中的都识别为标记候选而greaterThanToKeep决定保留最右侧多少个。以用例第一段为例第一行 raw avalue 为 a深度统计 1 → 保留最右 1 个标记得到内容 a第二行 raw gt; bvalue 为 b实体已解码深度统计 1 → 保留最右 1 个匹配即内容里的gt;剥离开头的得到内容gt; b。随后两块内容以空格拼接交由打印阶段统一补上外层标记最终产出 a gt; b。可见哪些是标记、哪些是内容最终由解码后的语义深度决定从而既不会把内容中的实体误删也不会把真正的标记误当内容。八、边界与兄弟用例同一机制的更多侧面同一目录下的其他用例从不同角度验证了这套机制的鲁棒性escaped-greater-than.md 验证\反斜杠转义在行首同样被当作标记剥离快照中 \ \合并为一行而 issue-19528.md 验证test\这种转义符紧跟文字的场景下\属于内容而非标记必须原样保留encoded-newline.md 验证编码换行符#10;、#xA;、NewLine;在引用块中的处理——getBlockquoteRawText中专门有一行newLineRegexp用于处理这些隐藏换行避免换行计数错乱导致标记剥离位置偏移indented-greater-than.md 验证行首带 4 空格或 Tab 缩进的也能被正确识别并合并。值得一提的是blockquote目录下的 format.test.js 同时对always、preserve、never三种模式运行测试说明 Prettier 要求引用块格式化的行为在三种模式下都保持稳定一致。九、如何本地复现与验证若要亲身体验上述行为可在仓库根目录完成依赖安装后运行该用例的测试yarn jest tests/format/markdown/blockquote/prose-wrap-always也可运行整个 blockquote 测试目录观察三种proseWrap模式下的全部快照yarn jest tests/format/markdown/blockquote另外你也可以将文中的输入保存为.md文件通过 Prettier CLI 直接查看格式化结果例如yarn prettier --parser markdown --prose-wrap always 输入文件.md仓库的 jest.config.js 与 package.json 中包含了测试相关的完整配置可供参考。十、工程启示与小结回顾整个机制这个看似平平无奇的测试用例背后实际上凝聚了 Prettier Markdown 格式化器的三个核心设计原则语义与字面分离node.value解码语义用于判断结构引用深度node.raw原始字面用于输出内容二者各司其职从根本上保证了结构判断准确、内容输出忠实标记识别的前瞻性rawBlockquoteRegexp穷举了字面、转义、命名实体、十/十六进制数字引用及各种大小写与前导零变体宁可多识别也不漏判为用户的多样写法兜底打印与预处理职责分明预处理阶段负责剥离原始标记getBlockquoteRawText打印阶段负责统一重建前缀align( , ...)前后呼应确保无论输入多么混乱输出始终规整。当你日后在 Prettier 中遇到引用块中的实体字符被异常处理或多行引用未按预期合并之类的问题时优先排查 get-blockquote-raw-text.js 的标记正则与 preprocess.js 的 raw/value 取舍逻辑往往就能直击要害。这正是开源仓库中一行测试快照背后隐藏着一套完整算法的典型范例。赞分享开发工具格式化CLI【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址https://gitcode.com/gh_mirrors/pr/prettier点击查看免费下载相关推荐Prettier Markdown 格式化blockquote 引号块中的编码换行符与 proseWrap: always 处理机制Prettier Markdown 格式化blockquote 引号块中的编码换行符与 proseWrap: always 处理机制 导读 本文以 Pre开发工具格式化CLIPrettier 对 Markdown 引用块Blockquote段落换行的格式化原理与实战Prettier 对 Markdown 引用块Blockquote段落换行的格式化原理与实战 本文围绕 Prettier 仓库中 tests/format/开发工具格式化CLIPrettier 格式化 Markdown 中的多行 HTML 块multiline-2 测试用例与源码实现解析Prettier 格式化 Markdown 中的多行 HTML 块multiline 2 测试用例与源码实现解析 Prettier 作为一款 opiniona开发工具格式化CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考