pulldown-cmark-frontmatter

此 crate 由与 pulldown-cmark crate 无关的人编写。

此 crate 使得在使用 pulldown-cmark Markdown 解析器时，可以轻松解析 Markdown 文档中的前置信息。

与许多其他前置信息样式不同，此 crate 强制执行基本的文档格式

• 可选的最高级（h1）标题
• 可选的代码块
• 剩余的 Markdown 文档

通过使用代码块而不是其他标记，大多数 Markdown 编辑软件可以更智能地处理语法高亮、错误等。

FrontmatterExtractor 类型将检测并返回文档中第一个元素是顶级标题的纯文本表示。当遍历 pulldown_cmark::Event 时，标题仍将返回。

在可选的最高级标题之后，如果遇到代码块，它将以 Frontmatter::code_block 返回。与标题不同，前置信息代码块将不会出现在遍历的 Event 中。

此仓库包括 frontmatter-example.md，它同时用于 HTML 渲染示例 和 提取器示例。

HTML 渲染示例

此示例展示了如何使用此 crate 与 pulldown-cmark 的 html 模块一起使用。它包含在仓库中的 examples/html.rs。

// This example renders the example Markdown to html using
// `pulldown_cmark::html`, while also extracting the frontmatter from
// Markdown.
let mut extractor = FrontmatterExtractor::new(pulldown_cmark::Parser::new(include_str!(
    "../frontmatter-example.md"
)));

// The only difference from using the FrontmatterExtractor and the regular
// pulldown_cmark::Parser is that you must pass a mutable reference to the
// extractor to be able to read the Frontmatter it extracts.
let mut rendered = String::new();
pulldown_cmark::html::push_html(&mut rendered, &mut extractor);
assert_eq!(rendered, include_str!("../frontmatter-example.html"));

let frontmatter = extractor.frontmatter.expect("frontmatter not detected");
assert_eq!(
    frontmatter.title.expect("title not detected"),
    "Frontmatter Example Document"
);
let code_block = frontmatter.code_block.expect("code block not detected");
assert_eq!(code_block.language.as_deref(), Some("toml"));
let attrs: ExampleAttributes = toml::from_str(&code_block.source).expect("invalid toml");
assert_eq!(attrs.author, "https://fosstodon.org/@ecton");

仓库包括 渲染后的 html 输出，以查看生成的 HTML 看起来像什么。

提取器示例

此示例从 Markdown 文档中提取前置信息，而无需解析整个文档。它包含在仓库中的 examples/extractor.rs。

// This example extracts the frontmatter from the Markdown,
// `FrontmatterExtractor::extract()` which stops parsing the Markdown
// document after the frontmatter extraction is complete.
let extractor = FrontmatterExtractor::from_markdown(include_str!("../frontmatter-example.md"));
let frontmatter = extractor.extract().expect("frontmatter not detected");
assert_eq!(
    frontmatter.title.expect("title not detected"),
    "Frontmatter Example Document"
);
let code_block = frontmatter.code_block.expect("code block not detected");
assert_eq!(code_block.language.as_deref(), Some("toml"));
let attrs: ExampleAttributes = toml::from_str(&code_block.source).expect("invalid toml");
assert_eq!(attrs.author, "https://fosstodon.org/@ecton");

开源许可

本项目，像所有来自Khonsu Labs的项目一样，是开源的。此存储库可在MIT许可证或Apache许可证2.0下使用。

要了解更多关于贡献的信息，请参阅CONTRIBUTING.md。