This crate was written by someone unaffiliated with the pulldown-cmark
crate.
This crate makes it easy to parse frontmatter contained within Markdown documents when using the pulldown-cmark Markdown parser.
Unlike many other frontmatter styles, this crate enforces a basic document format:
By utilizing a code block instead of other markers, most Markdown editing software can more intelligently handle syntax highlighting, errors, and more.
The FrontmatterExtractor type will detect and return a plain-text
representation of a top-level heading, if it's the first element in the
document. The heading will still be returned when iterating over the
pulldown_cmark::Events.
After the optional top-level heading, if a code block is encountered, it will be
returned as Frontmatter::code_block. Unlike the heading, the frontmatter code
block will not appear in the iterated Events.
This repository includes frontmatter-example.md which both the HTML rendering example and the extractor example use.
This example shows how to use this crate with pulldown-cmark's html module. It
is included in the repository at examples/html.rs.
``rust,ignore
// This example renders the example Markdown to html using
//pulldowncmark::html`, while also extracting the frontmatter from
// Markdown.
let mut extractor = FrontmatterExtractor::new(pulldowncmark::Parser::new(include_str!(
"../frontmatter-example.md"
)));
// The only difference from using the FrontmatterExtractor and the regular // pulldowncmark::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(); pulldowncmark::html::pushhtml(&mut rendered, &mut extractor); asserteq!(rendered, include_str!("../frontmatter-example.html"));
let frontmatter = extractor.frontmatter.expect("frontmatter not detected"); asserteq!( frontmatter.title.expect("title not detected"), "Frontmatter Example Document" ); let codeblock = frontmatter.codeblock.expect("code block not detected"); asserteq!(codeblock.language.asderef(), Some("toml")); let attrs: ExampleAttributes = toml::fromstr(&codeblock.source).expect("invalid toml"); assert_eq!(attrs.author, "https://fosstodon.org/@ecton"); ```
The repository includes the rendered html output to see what the produced HTML looks like.
This example extracts the frontmatter from a Markdown document without parsing the entire document. It is included in the repository at examples/extractor.rs.
rust,ignore
// 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");
This project, like all projects from Khonsu Labs, is open-source. This repository is available under the MIT License or the Apache License 2.0.
To learn more about contributing, please see CONTRIBUTING.md.