markdown-it-pyrs

目前处于测试版，欢迎反馈！

这是markdown-it.rs（以及 插件）的Python接口，使用Rust进行快速Markdown解析⚡️

该项目的目标是提供一个快速、安全、可扩展且易于使用的Markdown解析器。它与纯Python实现的markdown-it（markdown-it-py）相辅相成，我们旨在尽可能遵循该包的API。

如果你主要关注速度，这个库就是为你准备的。例如，当解析CommonMark规范文件时，markdown-it-pyrs的基准测试表明它比markdown-it-py快 20倍。

缺点是库供应商编译了Rust代码，因此

1. 解析器插件目前无法用Python编写并动态添加到解析器中。
2. 将其集成到如 pyiodide 和 py-script（但可能不会太久：https://discuss.python.org/t/support-wasm-wheels-on-pypi/21924/3）之类的环境中可能更加困难。

用法

首先安装包

pip install markdown-it-pyrs

然后像使用 markdown-it-py 一样使用它

from markdown_it_pyrs import MarkdownIt

md = MarkdownIt("commonmark").enable("table")
md.render("# Hello, world!")
# '<h1>Hello, world!</h1>\n'

markdown-it.rs 不生成标记流，而是直接生成一个 Node 树。这与 markdown-it-py 的 SyntaxTreeNode 类似，尽管 API 并不完全相同。（源映射也通过字节偏移提供，而不是仅限于行）

md = (
  MarkdownIt("commonmark")
  .enable("table")
  .enable_many(["linkify", "strikethrough"])
)
node = md.tree("# Hello, world!")
print(node.walk())
# [Node(root), Node(heading), Node(text)]
print(node.pretty(srcmap=True, meta=True))
# <root srcmap="0:15">
#   <heading srcmap="0:15">
#     level: 1
#     <text srcmap="2:15">
#       content: Hello, world!

注意： Node 类的属性，如 Node.attrs，返回底层数据的副本，因此修改它不会影响节点上存储的内容，例如：

from markdown_it_pyrs import Node
node = Node("name")
# don't do this!
node.attrs["key"] = "value"
print(node.attrs) # {}
# do this instead (Python 3.9+)
node.attrs = node.attrs | {"key": "value"}
print(node.attrs) # {"key": "value"}
# Node.children is only a shallow copy though, so this is fine
child = Node("child")
node.children = [child]
node.children[0].name = "other"
print(child.name) # "other"

命令行界面

还提供了一个命令行界面，可以使用以下方式使用：

echo "# Hello, world!" | markdown-it-pyrs html -
# <h1>Hello, world!</h1>
echo "# Hello, world!" | markdown-it-pyrs ast -
# <root>
#   <heading>
#     <text>

将 - 替换为要读取的文件名，有关更多选项，包括初始配置和启用插件，请参阅 markdown-it-pyrs --help。

初始配置

初始化 MarkdownIt("zero") 不会启用任何插件，因此您只能添加所需的插件。

使用 MarkdownIt("commonmark") 启用所有 CommonMark 插件。

使用 MarkdownIt("gfm") 启用所有 CommonMark 插件以及 GitHub Flavoured Markdown 插件。

插件

markdown-it.rs 中的所有语法规则都作为插件实现。可以通过调用带有插件名称的 enable 或 enable_many 来向解析器添加插件。以下是一些当前支持的插件：

CommonMark 块

• blockquote：带 > 的块引用
• code：缩进的代码块
• fence：反引号代码块
• heading：# ATX 标题
• hr：--- 水平规则
• lheading：--- 下划线 setext 标题
• list：* 无序列表和 1. 有序列表
• paragraph：段落
• reference：链接引用定义 [id]: src "title"

CommonMark 内联

• autolink：<http://example.com>
• backticks：`code`
• emphasis：_emphasis_、*emphasis*、**strong**、__strong__
• entity：&
• escape：反斜杠转义 \
• image：![alt](src "title")
• link：[text](src "title")、[text][id]、[text]
• newline：硬换行
• html_block：HTML 块
• html_inline：HTML 内联

GitHub Flavoured Markdown (https://github.github.com/gfm)

• 表格:

  | foo | bar |
  | --- | --- |
  | baz | bim |
  

• strikethrough：~~删除线~~

• tasklist：- [x] 任务列表项

• autolink_ext：使用“裸URL”如 https://example.com 和 www.example.com 扩展自动链接检测

• tagfilter：HTML 标签过滤，例如删除 <script> 标签

其他

• sourcepos：向渲染的 HTML 添加源映射，如下所示：<stuff data-sourcepos="1:1-2:3">，即 行:列-行:列
• replacements：排版替换，例如将 -- 替换为 —
• smartquotes：智能引号，例如将 " 替换为 “
• linkify：自动将 URL 链接化，使用 https://crates.io/crates/linkify（注意目前这仅匹配带有方案的 URL，例如 https://example.com）
• heading_anchors：添加标题锚点，默认与 GitHub 相同
• front_matter：YAML 前端内容
• footnote：Pandoc 风格脚注（见 https://pandoc.org/MANUAL.html#footnotes）
• deflist：定义列表（见 https://pandoc.org/MANUAL.html#definition-lists）

开发

我相当新手 Rust，所以如果您看到可以改进的地方，问题和 PR 欢迎提交！

PyO3 和 Maturin 用于构建 Python 包，通过将 markdown-it.rs 包装在一个 Python 模块中。

pre-commit 用于运行代码格式化和代码质量检查，而 tox 用于运行测试。

待办事项

改进

• 允许覆盖选项

  • lang_prefix: 代码块中语言类的前缀
  • quotes: 引号字符，用于智能引号

• 添加插件：...

• 允许为插件设置选项

  • 标题锚点
  • 禁用任务列表复选框
  • 脚注带有开启/关闭行内/收集/回引用的选项

在上游打开问题

• 没有 text_join 规则（用于连接相邻的 text 和 text_special 令牌）
• heading_anchors 插件不允许例如 GitHub 格式，其中非唯一性通过追加 -1、-2 等来解决，同时也移除了图像文本
• 捕获 AST 中的引用节点
• 禁用规则
• 更好的“跨语言”AST 表示
• linkify 和 normalize_url/commonmark_extras 测试失败的不同行为
• 智能引号的引号字符和 fence 的 lang_prefix 都应在运行时变量吗？（目前它们都必须在编译时指定）
• 修复 examples/ferris/block_rule.rs::FerrisBlockScanner::run 中的 docstring，该 docstring 当前描述的是 JS API 而不是新的 rust API
• 捕获嵌套内容的“分段”源映射，例如当源被拆分到多行并嵌套在其他块中时（可以在此处内联 https://github.com/rlidwka/markdown-it.rs/blob/6f906b38c8ffc3cc651e67b448b3655b7d0debb3/src/parser/inline/mod.rs#L115）
• 在核心规则中更简单地获取 root.ext 项目；似乎目前你必须在规则的末尾交换内存和重新交换，例如查看 InlineParserRule
• 允许 test_rules_at_line 解析调用规则的内容，这样其他规则可以根据调用规则（在 check 函数中）决定是否中断，我认为这将允许类似 alt 的行为（可能需要用于脚注定义解析）
  • 尽管如此，在不需要向后兼容性的情况下，我同意 djot 的第 7 个目标，即块元素不允许在不换行的情况下中断其他块元素
• 从 InlineRule.run 返回多个（连续）节点，例如 ((node1, length1), (node2, length2), ...)
  • 这将与 docutils 相似
• 在 Node 遍历方法中，允许函数返回一个值以指示是否继续遍历节点的子节点
  • 在遍历中，解析“路径”以到达当前节点，例如父节点列表，以允许反向跟踪
  • 类似于 https://github.com/syntax-tree/unist-util-visit-parents、https://github.com/syntax-tree/unist-util-visit 等
• 是否有方法使用 match 语句来匹配 Node 与 NodeValue 实现的 Node？（而不是使用 if/else 进行 Node.cast）
• 规则优先级作为整数（类似于 RST 转换优先级）
  • 目前只能指定在另一个规则或所有规则之前或之后
  • 对于插件来说，当使用 attrs 和向节点值添加字段时可能有些不清楚

维护