README

moxio/commonmark-ext-fancy-lists

league/commonmark Markdown 解析器的扩展，用于支持有序列表的额外编号类型。

使用基于Pandoc支持的非官方 Markdown 语法。有关详细信息，请参阅下方的语法部分。

解析器是league/commonmark中原始的ListBlockStartParser和相关类的修改版本，由Colin O'Dell创建，并使用BSD-3-Clause许可证。它反过来基于CommonMark JS参考实现，由John MacFarlane创建。

要求

此库需要PHP版本7.4或更高版本，以及league/commonmark的2.x版本。

安装

使用composer将其作为依赖项安装

$ composer require --dev moxio/commonmark-ext-fancy-lists

用法

将FancyListsExtension添加到您的CommonMark环境实例中，然后即可使用

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\MarkdownConverter;
use Moxio\CommonMark\Extension\FancyLists\FancyListsExtension;

$environment = new Environment();
$environment->addExtension(new CommonMarkCoreExtension());
$environment->addExtension(new FancyListsExtension());

// Use $environment when building your MarkdownConverter
$converter = new MarkdownConverter($environment);
echo $converter->convertToHtml('
a) foo
b) bar
c) baz
');

有关使用扩展的更多信息，请参阅CommonMark文档。

语法

支持的 Markdown 语法基于Pandoc使用的语法。

简单示例

i. foo
ii. bar
iii. baz

这将产生如下HTML输出

<ol type="i">
  <li>foo</li>
  <li>bar</li>
  <li>baz</li>
</ol>

更复杂的示例

c. charlie
#. delta
   iv) subfour
   #) subfive
   #) subsix
#. echo

关于语法规则的简短描述

• 除了数字外，还可以使用字母（大小写）和罗马数字（大小写）来编号有序列表项。像用数字标记的列表一样，它们后面需要跟一个单个的右括号或句号。
• 更改列表标记类型（大小写之间或'数字'后的符号）将开始一个新的列表。
• 第一个列表项的数字决定了列表的编号。如果第一个列表项编号为"b"，则下一个列表项将编号为"c"，即使它在源中标记为"z"。这对应于league/commonmark的正常行为，并基本上实现了Pandoc的startnum扩展。
• 如果第一个列表项编号为"I"或"i"，则列表被认为是使用罗马数字编号，从1开始。如果列表以其他单个字母开头，该字母可以解释为罗马数字，则列表使用字母编号：标记为"C."的第一个列表项使用从3开始的字母，而不是从100开始的罗马数字。
• 在后续列表项中，可以使用这些符号而不产生歧义：在"B."、"C."、"D."中，"C"是字母"C"；在"IC."、"C."、"CI."中，"C"是罗马数字100。
• 可以使用"#"代替任何数字来继续列表。如果一个列表的第一个项目用"#"标记，那么这个列表将编号为"1"、"2"、"3"等。
• 列表标记由单个大写字母后跟一个句点（包括罗马数字如“I.”或“V.”）组成，需要至少后跟两个空格（理由）。

以上所有内容都与 Pandoc 的工作方式完全兼容。与 Pandoc 的语法有两个小差异

• 此插件不支持括号内的列表编号，因为 Commonmark 规范也不支持使用阿拉伯数字编号的列表中的这些编号。
• Pandoc 不允许任何列表中断段落。遵循 Commonmark 规范（仅允许以 1 开头的列表中断段落）的精神，此插件允许以“A”，“a”，“I”或“i”（即所有“首位数字”）开头的列表中断段落。同样适用于“#”通用编号列表项标记。

配置

所有配置选项都放在 fancy_lists 键下。您可以在创建 Environment 类时指定配置

use League\CommonMark\Environment\Environment;

$environment = new Environment([
    'fancy_lists' => [
        'allow_ordinal' => true,
        // ...
    ],
]);

有关如何指定配置的更多详细信息，请参阅 league/commonmark 的 文档。

支持的配置选项

• allow_ordinal - 是否允许在数字后添加 序数指示符（º），如法律文件中常见（默认：false）。如果此选项启用，则类似

  1º. foo
  2º. bar
  3º. baz

  的输入将转换为

  <ol class="ordinal">
    <li>foo</li>
    <li>bar</li>
    <li>baz</li>
  </ol>

  您需要 自定义 CSS 来根据 ordinal 类将序数指示符重新插入到显示的输出中。

  由于序数指示符通常与其他字符（如度符号）混淆，因此这些字符被视为可接受的，并认为与序数指示符等效。

• allow_multi_letter - 是否允许多字母字母数字，以编号超过 26 的列表（默认：false）。如果此选项启用，则类似

  AA. foo
  AB. bar
  AC. baz

  的输入将转换为

  <ol type="A" start="27">
    <li>foo</li>
    <li>bar</li>
    <li>baz</li>
  </ol>

  的多字母字母数字最多由 3 个字符组成，这对于典型列表应该足够。当列表以既可以表示罗马数字也可以表示多字母字母数字的数字开头时，例如“II”，则被认为是罗马数字。

版本控制

此项目遵循 语义版本控制。

贡献

欢迎对此项目做出贡献。在报告问题时要包括重现问题的输入以及预期的输出。在提交 PR 时，请包括您的更改的测试。

许可证

此项目在 MIT 许可证下发布。

Treeware

此软件包是 Treeware。如果您在生产中使用它，那么我们非常感谢您为我们买下一棵树，以感谢我们的工作。通过为 Treeware 森林做出贡献，您将为当地家庭创造就业机会并恢复野生动物栖息地。

由荷兰代尔夫特的 Moxio 团队用爱、咖啡和乐趣制作。有兴趣加入我们出色的团队？查看我们的 职位空缺（荷兰语）。