• 后端

导读

本文围绕 Parsedown 官方测试用例 test/data/compound_list.md 与其期望输出 test/data/compound_list.html，深入剖析一个核心 Markdown 解析问题：列表项内部如何承载多个块级元素（多个段落、引用块 blockquote）。通过对照源码 Parsedown.php 中blockList、blockListContinue、blockQuote与li等关键方法的实现，你将掌握 Parsedown 对"复合列表"（compound list）的判定规则、松散列表（loose list）的触发条件，以及嵌套块级内容的渲染方式，并学会用官方测试套件验证自己的理解。

一、测试用例本体：6 行 Markdown，四种块级结构

compound_list.md全文仅有 6 行，但它覆盖了复合列表中极具代表性的两种形态：

- paragraph paragraph - paragraph > quote

按行分解：

期望输出compound_list.html明确了渲染语义：

<ul> <li> <p>paragraph</p> <p>paragraph</p> </li> <li> <p>paragraph</p> <blockquote> <p>quote</p> </blockquote> </li> </ul>

关键结论一目了然：列表项内部可以包含多个块级元素，且每一项都被<p>包裹，说明这是典型的"松散列表"（loose list）——因为第 1 行到第 3 行之间出现了空行分隔。

二、复合列表为何成立：从"块级容器"的视角理解列表

Parsedown 中列表不是简单的"一行一<li>"的字符串拼接，而是一个可容纳任意块级子结构的容器。这一设计直接体现在 Parsedown.php 中：

$Block['li'] = array( 'name' => 'li', 'handler' => array( 'function' => 'li', 'argument' => !empty($matches[3]) ? array($matches[3]) : array(), 'destination' => 'elements' ) ); $Block['element']['elements'] []= & $Block['li'];

li的 handler 把列表项内的全部内容行交给li()方法递归处理，而 li() 又调用linesElements()对内容重新做一次完整的块级解析：

protected function li($lines) { $Elements = $this->linesElements($lines); if ( ! in_array('', $lines) and isset($Elements[0]) and isset($Elements[0]['name']) and $Elements[0]['name'] === 'p' ) { unset($Elements[0]['name']); } return $Elements; }

这正是"复合列表"的底层根基：列表项的正文不是纯文本，而是被当作一段独立的 Markdown 输入重新解析。linesElements()（见 Parsedown.php）是 Parsedown 的块级主循环，同一套状态机既驱动顶层文档，也驱动每个列表项，因此段落、引用块、代码块、子列表等块级元素在列表项内部天然可用。

2.1 空行与interrupted标记：列表从紧凑变为松散

compound_list.md中第 1 项内部出现的空行，是理解输出结果中<p>标签的关键。在linesElements()中，空行会将当前块标记为被打断（Parsedown.php）：

if (chop($line) === '') { if (isset($CurrentBlock)) { $CurrentBlock['interrupted'] = (isset($CurrentBlock['interrupted']) ? $CurrentBlock['interrupted'] + 1 : 1 ); } continue; }

在 blockListContinue() 中，一旦检测到列表项内存在interrupted且随后仍有内容行续接，就会设置$Block['loose'] = true：

if (isset($Block['interrupted'])) { $Block['li']['handler']['argument'] []= ''; $Block['loose'] = true; unset($Block['interrupted']); }

随后 blockListComplete() 在列表结束时，为松散列表的每个<li>补一个空行参数，使其内容按多段落处理：

protected function blockListComplete(array $Block) { if (isset($Block['loose'])) { foreach ($Block['element']['elements'] as &$li) { if (end($li['handler']['argument']) !== '') { $li['handler']['argument'] []= ''; } } } return $Block; }

而li()中的一行if ( ! in_array('', $lines) ... unset($Elements[0]['name'])则说明：只有当列表项内容不含空行（紧凑列表）时，首个段落才会被去掉<p>包裹（形成常见的紧凑渲染- item）。compound_list.md的两项都含空行，因此每个段落都保留<p>标签——这正是期望输出 HTML 中每个<li>内部段落均有<p>的原因。

2.2 缩进对齐：列表项内容如何"贴附"到所在项

compound_list.md中第二个段落和引用块都缩进了 2 个空格。这个缩进量并非随意，而是与列表标记-的宽度对应。在 blockList() 中：

if (preg_match('/^('.$pattern.'([ ]++|$))(.*+)/', $Line['text'], $matches)) { $contentIndent = strlen($matches[2]); ... }

-的 marker 长度为 2，因此后续行只要缩进 >= 2（即$requiredIndent = $Block['indent'] + strlen($Block['data']['marker'])，见 blockListContinue()），就会被判定为该列表项的内容行；在 blockListContinue() 中，这些行通过substr($Line['body'], $requiredIndent)剥离缩进后追加进当前li的参数数组：

if ($Line['indent'] >= $requiredIndent) { ... $text = substr($Line['body'], $requiredIndent); $Block['li']['handler']['argument'] []= $text; return $Block; }

正是这一"缩进即归属"的规则，让第 6 行的> quote进入第 2 个<li>的参数序列，再交由li()→linesElements()递归识别为引用块。

三、嵌套引用块：blockQuote在列表项内的二次触发

第 6 行> quote被剥离 2 空格缩进后，其有效文本为> quote。当li()将这些行送入linesElements()重新做块级解析时，blockQuote() 便以顶层等价的身份命中：

protected function blockQuote($Line) { if (preg_match('/^>[ ]?+(.*+)/', $Line['text'], $matches)) { $Block = array( 'element' => array( 'name' => 'blockquote', 'handler' => array( 'function' => 'linesElements', 'argument' => (array) $matches[1], 'destination' => 'elements', ) ), ); return $Block; } }

blockquote的 handler 同样指向linesElements()，于是quote文本继续被解析为段落，最终生成<blockquote><p>quote</p></blockquote>。整条解析链路可以概括为：

列表行(- paragraph) → blockList 创建 ul/li 容器 → blockListContinue 依据缩进与空行累积各项内容行 → blockListComplete 将松散列表补齐空行参数 → li() 递归调用 linesElements() → blockParagraph 生成 <p>paragraph</p> → blockQuote 生成 <blockquote><p>quote</p></blockquote>

从中可以推断：列表项内的块级嵌套是通过"递归重启块级状态机"实现的，而非特化的列表分支逻辑。这也是为什么 Parsedown 可以支持列表项内嵌套任意深度的其他块级元素。

四、如何在测试套件中复现与验证

compound_list.md是 Parsedown 官方测试夹具的一部分。测试入口在 test/ParsedownTest.php，其test_方法（test/ParsedownTest.php）逐对读取data/*.md与data/*.html：

$markdown = file_get_contents($dir . $test . '.md'); $expectedMarkup = file_get_contents($dir . $test . '.html'); $actualMarkup = $this->Parsedown->text($markdown); $this->assertEquals($expectedMarkup, $actualMarkup);

运行方式（项目已提供 phpunit.xml.dist 与 composer.json）：

composer install # 安装 PHPUnit 依赖 vendor/bin/phpunit # 运行全部 Parsedown 测试 vendor/bin/phpunit --filter test_compound_list # 仅运行 compound_list 用例

若修改了compound_list.md内容，需同步更新compound_list.html，否则测试将因期望输出不匹配而失败——这正是用"输入/输出夹具对"锁死解析语义的典型做法。

五、与相邻测试用例的对照：复合列表的边界行为

test/data/目录下还有一组与复合列表语义紧密相关的夹具，可作为延伸阅读：

• test/data/paragraph_list.md：列表前后的独立段落与空行分隔关系，对应输出paragraph_list.html；
• test/data/multiline_list_paragraph.md：列表项内多行连续文本如何归入同一段落（紧凑列表的<p>剥离行为在此可见端倪）；
• test/data/multiline_lists.md 与 test/data/compound_blockquote.md：更复杂的多块级组合场景；
• test/data/compound_emphasis.md：块级结构内部的跨行行内强调解析。

将这些用例与compound_list.md对照阅读，可以完整勾勒出 Parsedown 对"块级容器嵌套"的统一处理模型：无论是列表、引用块还是代码块，其内部内容一律通过 handler 递归复用linesElements()状态机，从而在保证解析器核心精简的同时，获得极强的嵌套表达能力。

结语

compound_list.md虽然只有 6 行，却是理解 Parsedown 块级解析架构的最佳切入口。它的期望输出揭示了三个关键事实：其一，列表是块级容器而非文本拼接；其二，空行会驱动loose标记，决定段落是否包裹<p>；其三，列表项内容通过li()→linesElements()递归重解析，使得段落、引用块等块级元素可以任意嵌套。掌握这一模型后，你在使用或二次开发 Parsedown 时，便能准确预判复合列表、嵌套引用等场景的输出结果，也能更高效地定位 Parsedown.php 中的相关实现。

• 后端