Comrak: A CommonMark and GFM compatible Markdown parser and renderer in Rust

4 months ago 34

Rust port of github's cmark-gfm.

Compliant with CommonMark 0.31.2 in default mode. GFM support synced with release 0.29.0.gfm.13.

Specify it as a requirement in Cargo.toml:

[dependencies] comrak = "0.39"

Comrak's library supports Rust 1.65+.

Anywhere with a Rust toolchain:
- cargo install comrak
Many Unix distributions:
- pacman -S comrak
- brew install comrak
- dnf install comrak
- nix run nixpkgs#comrak

You can also find builds I've published in GitHub Releases, but they're limited to machines I have access to at the time of making them! webinstall.dev offers curl | shell-style installation of the latest of these for your OS.

Click to expand the CLI --help output.

A 100% CommonMark-compatible GitHub Flavored Markdown parser and formatter Usage: comrak [OPTIONS] [FILE]... Arguments: [FILE]... CommonMark file(s) to parse; or standard input if none passed Options: -c, --config-file <PATH> Path to config file containing command-line arguments, or 'none' [default: /home/runner/.config/comrak/config] -i, --inplace To perform an in-place formatting --hardbreaks Treat newlines as hard line breaks --smart Use smart punctuation --github-pre-lang Use GitHub-style <pre lang> for code blocks --full-info-string Enable full info strings for code blocks --gfm Enable GitHub-flavored markdown extensions: strikethrough, tagfilter, table, autolink, and tasklist. Also enables --github-pre-lang and --gfm-quirks --gfm-quirks Enables GFM-style quirks in output HTML, such as not nesting tags, which otherwise breaks CommonMark compatibility --relaxed-tasklist-character Enable relaxing which character is allowed in a tasklists --relaxed-autolinks Enable relaxing of autolink parsing, allow links to be recognized when in brackets and allow all url schemes --tasklist-classes Output classes on tasklist elements so that they can be styled with CSS --default-info-string <INFO> Default value for fenced code block's info strings if none is given --unsafe Allow raw HTML and dangerous URLs --gemojis Translate gemojis into UTF-8 characters --escape Escape raw HTML instead of clobbering it --escaped-char-spans Wrap escaped characters in span tags -e, --extension <EXTENSION> Specify extension name(s) to use Multiple extensions can be delimited with ",", e.g. --extension strikethrough,table [possible values: strikethrough, tagfilter, table, autolink, tasklist, superscript, footnotes, description-lists, multiline-block-quotes, math-dollars, math-code, wikilinks-title-after-pipe, wikilinks-title-before-pipe, underline, subscript, spoiler, greentext, alerts] -t, --to <FORMAT> Specify output format [default: html] [possible values: html, xml, commonmark] -o, --output <FILE> Write output to FILE instead of stdout --width <WIDTH> Specify wrap width (0 = nowrap) [default: 0] --header-ids <PREFIX> Use the Comrak header IDs extension, with the given ID prefix --front-matter-delimiter <DELIMITER> Ignore front-matter that starts and ends with the given string --syntax-highlighting <THEME> Syntax highlighting for codefence blocks. Choose a theme or 'none' for disabling [default: base16-ocean.dark] --list-style <LIST_STYLE> Specify bullet character for lists (-, +, *) in CommonMark output [default: dash] [possible values: dash, plus, star] --sourcepos Include source position attribute in HTML and XML output --ignore-setext Ignore setext headers --ignore-empty-links Ignore empty links --experimental-minimize-commonmark Minimize escapes in CommonMark output using a trial-and-error algorithm -h, --help Print help information (use `-h` for a summary) -V, --version Print version information By default, Comrak will attempt to read command-line options from a config file specified by --config-file. This behaviour can be disabled by passing --config-file none. It is not an error if the file does not exist.

And there's a Rust interface. You can use comrak::markdown_to_html directly:

use comrak::{markdown_to_html, Options}; assert_eq!(markdown_to_html("Hello, **世界**!", &Options::default()), "Hello, 世界!\n");

Or you can parse the input into an AST yourself, manipulate it, and then use your desired formatter:

use comrak::nodes::NodeValue; use comrak::{format_html, parse_document, Arena, Options}; fn replace_text(document: &str, orig_string: &str, replacement: &str) -> String { // The returned nodes are created in the supplied Arena, and are bound by its lifetime. let arena = Arena::new(); // Parse the document into a root `AstNode` let root = parse_document(&arena, document, &Options::default()); // Iterate over all the descendants of root. for node in root.descendants() { if let NodeValue::Text(ref mut text) = node.data.borrow_mut().value { // If the node is a text node, perform the string replacement. *text = text.replace(orig_string, replacement); } } let mut html = vec![]; format_html(root, &Options::default(), &mut html).unwrap(); String::from_utf8(html).unwrap() } fn main() { let doc = "This is my input.\n\n1. Also [my](#) input.\n2. Certainly *my* input.\n"; let orig = "my"; let repl = "your"; let html = replace_text(&doc, &orig, &repl); println!("{}", html); // Output: // // This is your input. // <ol> // <li>Also <a href="#">your</a> input.</li> // <li>Certainly your input.</li> // </ol> }

For a slightly more real-world example, see how I generate my GitHub user README from a base document with embedded YAML, which itself has embedded Markdown, or check out some of Comrak's dependents on crates.io or on GitHub.

As with cmark and cmark-gfm, Comrak will scrub raw HTML and potentially dangerous links. This change was introduced in Comrak 0.4.0 in support of a safe-by-default posture, and later adopted by our contemporaries. :)

To allow these, use the unsafe_ option (or --unsafe with the command line program). If doing so, we recommend the use of a sanitisation library like ammonia configured specific to your needs.

Comrak supports the five extensions to CommonMark defined in the GitHub Flavored Markdown Spec:

Comrak additionally supports its own extensions, which are yet to be specced out (PRs welcome!):

Superscript
Header IDs
Footnotes
Description lists
Front matter
Multi-line blockquotes
Math
Emoji shortcodes
Wikilinks
Underline
Spoiler text
"Greentext"

By default none are enabled; they are individually enabled with each parse by setting the appropriate values in the ExtensionOptions struct.

Fenced code block syntax highlighting

You can provide your own syntax highlighting engine.

Create an implementation of the SyntaxHighlighterAdapter trait, and then provide an instance of such adapter to Plugins.render.codefence_syntax_highlighter. For formatting a Markdown document with plugins, use the markdown_to_html_with_plugins function, which accepts your plugins object as a parameter.

See the syntax_highlighter.rs and syntect.rs examples for more details.

syntect is a syntax highlighting library for Rust. By default, comrak offers a plugin for it. In order to utilize it, create an instance of plugins::syntect::SyntectAdapter and use it in your Plugins option.

Comrak's design goal is to model the upstream cmark-gfm as closely as possible in terms of code structure. The upside of this is that a change in cmark-gfm has a very predictable change in Comrak. Likewise, any bug in cmark-gfm is likely to be reproduced in Comrak. This could be considered a pro or a con, depending on your use case.

The downside, of course, is that the code often diverges from idiomatic Rust, especially in the AST's extensive use of RefCell, and while contributors have made it as fast as possible, it simply won't be as fast as some other CommonMark parsers depending on your use-case. Here are some other projects to consider:

Raph Levien's pulldown-cmark. It's very fast, uses a novel parsing algorithm, and doesn't construct an AST (but you can use it to make one if you want). cargo doc uses this, as do many other projects in the ecosystem.
markdown-rs (1.x) looks worth watching.
Know of another library? Please open a PR to add it!

As far as I know, Comrak is the only library to implement all of the GitHub Flavored Markdown extensions rigorously.

mdex - Elixir bindings for this library built with Rustler. Available on Hex as mdex.

comrak (Python package) — Python bindings for this library built with PyO3. Available on PyPI as comrak, benchmarked at 15-60x faster than pure Python alternatives.

commonmarker - Ruby bindings for this library built with Magnus/rb-sys. Available on RubyGems as commonmarker.

You'll need to install hyperfine, and CMake if you want to compare against cmark-gfm.

If you want to just run the benchmark for the comrak binary itself, run:

This will build Comrak in release mode, and run benchmark on it. You will see the time measurements as reported by hyperfine in the console.

The Makefile also provides a way to run benchmarks for comrak current state (with your changes), comrak main branch, cmark-gfm, pulldown-cmark and markdown-it.rs. You'll need CMake, and ensure submodules are prepared.

This will build and run benchmarks across all, and report the time taken by each as well as relative time.

Contributions are highly encouraged; if you'd like to assist, consider checking out the good first issue label! I'm happy to help provide direction and guidance throughout, even if (especially if!) you're new to Rust or open source.

Where possible I practice Optimistic Merging as described by Peter Hintjens. Please keep the code of conduct in mind too.

Thank you to Comrak's many contributors for PRs and issues opened!