Jotdown

API 文档 | 在线演示 | Crate | 仓库

Jotdown 是一个针对 Djot 标记语言的 Rust 拉解析库。它将 Djot 文档解析成一系列事件，并可能将这些事件渲染成 HTML。

Jotdown 旨在快速高效，使用尽可能少的分配。API 应该使用惯用的 Rust 语法，易于使用且灵活。事件接口允许客户端构建 AST 或生成任何类型的输出格式。它还允许在生成输出之前对文档执行过滤。Jotdown 旨在功能完善，并在输出方面匹配 语法参考 和 参考实现。

另一个目标是保持实现最小化并降低构建时间。当前实现没有依赖项，如果添加了主要非必需功能或使用了更大的依赖项，应使用功能标志作为可选项。

Jotdown 支持 Rust 2021 版本，即 Rust 1.56 及以上版本。

用法

Jotdown 主要是一个解析库，但也包含一个最小的 CLI 实现和简单的网络演示版本。

库

Jotdown API 受 pulldown-cmark 启发，总体上非常相似。Jotdown crate 包含源代码文档，渲染版本可在 https://docs.rs/jotdown 查看。

虽然 Jotdown 可以使用，但它仍然处于早期开发阶段，API 可能会频繁发生重大变更。Djot 语法也处于非常早期阶段，也可能发生重大变化。

CLI

Jotdown crate 包含一个 CLI 的最小实现，它简单地从标准输入读取并将 HTML 写入标准输出。可以从该仓库构建并使用 cargo 在本地运行。

$ cargo build --release
$ echo "hello world" | ./target/release/djot
<p>hello world</p>

或者，可以从 crates.io 仓库安装，只需简单执行以下命令

$ cargo install jotdown

它将被放置在 ~/.cargo/bin/jotdown。

网络演示

网络演示是Jotdown的一个版本，编译为WebAssembly，可以在网络浏览器中运行。它适用于实验djot语法和探索发出的事件或渲染的输出。

在线版本可在https://hllmn.net/projects/jotdown/demo找到。它也可以本地运行

$ cd examples/jotdown_wasm
$ make run

您可能需要安装wasm-pack 并确保您的Rust编译器有WebAssembly后端。

状态

正确性

截至编写时，Jotdown实现了Djot语法的所有当前功能，包括

• 链接、图片，可以是内联的或带有参考链接定义的
• 自动链接
• 内联排版
  • 强调
  • 突出显示
  • 上标/下标
  • 插入/删除
  • 智能标点符号
• 内联文本、代码和代码块
• 数学
• 换行符
• 注释
• 符号
• 标题，包括层次性部分和自动链接
• 块引用
• 列表
  • 无序列表
  • 有序列表
  • 任务
  • 定义
• 原始内联和块
• 主题分隔符
• 管道表格
• 属性，用于内联和块元素
• 内联范围和div块
• 脚注

在某些情况下，HTML输出与参考实现并不完全相同。有两个测试套件可以比较Jotdown的HTML输出与参考实现。一个使用参考实现的单元测试并在Jotdown中运行它们。可以通过以下方式运行

$ make test_html_ut

另一个目标使用参考实现为其基准文件生成HTML输出，并将其与Jotdown的输出进行比较

$ make test_html_ref

请注意，运行参考实现需要node。

性能

有可用的基准来衡量性能。输入文件是从参考实现借用的。要获取输入文件，将它们符号链接到bench目录，运行

make bench

有两个单独的基准套件可以运行；criterion和iai。criterion衡量统计实时性能，而iai衡量执行指令和内存访问的精确数量。要运行criterion基准，使用

cargo bench -p bench-crit [filter]

或者，如果已安装cargo-criterion

cargo criterion -p bench-crit -- [filter]

要运行iai基准，使用

cargo bench -p bench-iai