CommonMark + GFM compatible Markdown parser and renderer
CommonMark + GFM compatible Markdown parser and renderer
Comrak is a CommonMark and GitHub Flavored Markdown compatible parser and renderer, written in Rust.
Compliant with CommonMark 0.31.2 by default.
Specify it as a requirement in Cargo.toml:
[dependencies]
comrak = "0.55"Comrak's library supports Rust 1.85+.
cargo install comrakcargo binstall comrakpacman -S comrakbrew install comrakdnf install comraknix run nixpkgs#comrakscoop install comrakYou 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, including Windows.
--help output.$ comrak --help…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("¡Olá, **世界**!", &Options::default()),
"<p>¡Olá, <strong>世界</strong>!</p>\n"
);Or you can parse the input into an AST yourself, manipulate it, and then use your desired formatter:
…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 r#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!):
By default none are enabled; they are individually enabled with each parse by setting the appropriate values in the
options::Extension struct.
The default HTML formatter can be partially specialised, to
allow customising the output for certain node types without
having to reimplement a whole formatter. See the docs for
comrak::create_formatter
for details.
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 original design goal was to model the upstream
cmark-gfm as closely as possible in
terms of code structure. Many years have passed since its inception, and the codebases
have since grown considerably apart. It does remain the case, though, that there
are bugs in cmark-gfm that are likely in Comrak too, as a result.
Over the years, we have increasingly opted to fix such bugs, rather than
maintain upstream compatibility at all costs. cmark-gfm no longer appears to
be under active maintenance, but Comrak is a living and growing project.
This library offers an AST backed by
typed_arena, with extensive
use of RefCell in the core node type to provide mutable access with
parent/sibling/child pointers. This can produce non-idiomatic-looking code,
though in practice it has proven very usable.
For whatever reason, Comrak may not meet your requirements. Here are some projects and resources to also consider:
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.commonmarker.mdex.comrak, benchmarked at 15-60x faster than pure Python alternatives.comrak with additional APIs exposed, including the AST.
Available on PyPI as comrak-ext.@nick/comrak.Comrak is used in a few Rust-y places, and more beyond:
deno_doc.I'd be really happy to add your site or app here, just open a PR or issue. :)
[^reddit]: And they contributed some really nice changes, years back. Then management went and sold their user base and all their credibility. What can you do.
We offer some tools to perform stdin-to-stdout benchmarking of Comrak with its contemporaries. In this respect, Comrak is not and will not be the fastest: some alternatives do not construct an AST in this scenario.
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:
make bench-comrakThis 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.
make bench-allThis 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!
Please report security issues to the author at <[email protected]>. If you have a GitHub account, you are welcome to use its interface to privately report security issues.
This policy is based on and inspired by Servo's AI contributions policy (permalink) and QEMU's Use of AI-generated content policy. Please see those links for a more detailed analysis.
Contributions must not include content generated by large language models or other probabilistic tools, including but not limited to Copilot or ChatGPT. This policy covers code, documentation, pull requests, issues, comments, and any other contributions to Comrak.
Asherah Connor <[email protected]>
Copyright (c) 2017–2026, Comrak contributors. Licensed under the 2-Clause BSD License.
cmark itself is is copyright (c) 2014, John MacFarlane.
See COPYING for all the details.
No open issues yet, or sync has not completed.