Skip to content
philomena-devPublic
forked from kivikakk/comrak

About

CommonMark + GFM compatible Markdown parser and renderer

Resources

Code of conduct

Contributing

Stars

1 star

Watchers

0 watching

Forks

 
 

Repository files navigation

Build status CommonMark: 652/652 GFM: 670/670 crates.io version docs.rs OpenSSF Best Practices

Comrak is a CommonMark and GitHub Flavored Markdown compatible parser and renderer, written in Rust.

Compliant with CommonMark 0.31.2 by default.

Installation

Specify it as a requirement in Cargo.toml:

[dependencies]
comrak = "1.1"

Comrak's library supports Rust 1.89+.

CLI

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

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, including Windows.

Usage

Click to expand the CLI --help output.
$ comrak --help
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
          Reformat CommonMark files in-place

  -t, --to <FORMAT>
          Specify output format
          
          [default: html]
          [possible values: html, xml, commonmark]

  -o, --output <FILE>
          Write output to FILE instead of stdout

      --syntax-highlighting <THEME>
          Syntax highlighting for fenced code blocks; 'css' for CSS classes (default), a theme name
          for inline styles, or 'none' to disable
          
          [default: css]

      --hardbreaks
          Treat newlines as hard line breaks

      --smart
          Replace punctuation like "this" with smart punctuation like “this”

      --github-pre-lang
          Use GitHub-style "<pre lang>" for code blocks

      --full-info-string
          Include words following the code block info string in a data-meta attribute

      --gfm
          Enable GitHub-flavored markdown extensions: strikethrough, table, autolink, and tasklist.
          Also enables --github-pre-lang and --gfm-quirks

      --gfm-quirks
          Use GFM-style quirks in output HTML, such as not nesting <strong> tags, which otherwise
          breaks CommonMark compatibility

      --relaxed-tasklist-character
          Permit any character inside a tasklist item, not just " ", "x", or "X"

      --tasklist-in-table
          Allow task list items in table cells

      --relaxed-autolinks
          Relax autolink parsing: allows links to be recognised when in brackets, permits all URL
          schemes, and permits domains without a TLD (like "http://localhost")

      --tasklist-classes
          Include "task-list-item" and "task-list-item-checkbox" classes on

      --default-info-string <INFO>
          Default value for fenced code block's info strings if none is given

      --unsafe
          Allow inline and block HTML (unless --escape is given), and permit

      --gemoji
          Translate gemoji like ":thumbsup:" into Unicode emoji like "👍"

      --escape
          Escape raw HTML, instead of clobbering it; takes precedence over --unsafe

      --escaped-char-spans
          Wrap escaped Markdown characters in "<span data-escaped-char>" in HTML

  -e, --extension <EXTENSION>
          Specify extensions to use
          
          Multiple extensions can be delimited with ",", e.g. '--extension strikethrough,table', or
          you can pass --extension/-e multiple times
          
          [possible values: strikethrough, table, grid-table, autolink, tasklist, superscript,
          footnotes, inline-footnotes, description-lists, multiline-block-quotes, math-dollars,
          math-dollars-block, math-latex, math-code, wikilinks-title-after-pipe,
          wikilinks-title-before-pipe, underline, subscript, spoiler, greentext, ofm-comments,
          ofm-block-ids, alerts, ofm-callouts, cjk-friendly-emphasis, subtext, highlight, insert,
          phoenix-heex, block-directive, header-attributes, fenced-code-attributes,
          inline-code-attributes, link-attributes]

      --width <WIDTH>
          Specify wrap width for output CommonMark, or '0' to disable wrapping
          
          [default: 0]

      --header-id-prefix <PREFIX>
          Use the Comrak header IDs extension, with the given ID prefix

      --header-id-prefix-in-href
          Apply the header ID prefix to the href anchor as well

      --front-matter-delimiter <DELIMITER>
          Detect frontmatter that starts and ends with the given string, and do not include it in
          the resulting document

      --list-style <LIST_STYLE>
          Specify bullet character for lists ("-", "+", "*") in CommonMark output
          
          [default: dash]
          [possible values: dash, plus, star]

      --alert-style <ALERT_STYLE>
          Specify alert style (<div> vs <aside>) in HTML output
          
          [default: specific]
          [possible values: specific, semantic]

      --sourcepos
          Include source position attributes in HTML and XML output

      --attributes
          Render parsed attributes in HTML output (requires --unsafe)

      --ignore-setext
          Do not parse setext headers

      --ignore-empty-links
          Do not parse empty links

      --sourcepos-chars
          Report column positions in sourcepos as a Unicode character count rather than UTF-8 byte
          offsets

      --experimental-minimize-commonmark
          Minimise escapes in CommonMark output using a trial-and-error algorithm

      --compact
          Suppress pretty-printing newlines between block-level HTML elements

      --grid-table-widths
          Write <colgroup> in HTML output

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

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("¡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:

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_mut().value {
            // If the node is a text node, perform the string replacement.
            *text = text.to_mut().replace(orig_string, replacement).into()
        }
    }

    let mut html = String::new();
    format_html(root, &Options::default(), &mut html).unwrap();

    html
}

fn main() {
    let doc = "Hello, pretty world!\n\n1. Do you like [pretty](#) paintings?\n2. Or *pretty* music?\n";
    let orig = "pretty";
    let repl = "beautiful";
    let html = replace_text(doc, orig, repl);

    println!("{}", html);
    // Output:
    //
    // <p>Hello, beautiful world!</p>
    // <ol>
    // <li>Do you like <a href="#">beautiful</a> paintings?</li>
    // <li>Or <em>beautiful</em> music?</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.

Security

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.

Extensions

Comrak supports four (!) of the five extensions to CommonMark defined in the GitHub Flavored Markdown Spec, and have written up our own specs for them in the spirit of CommonMark:

We removed the Disallowed Raw HTML (a.k.a. tagfilter) extension in Comrak 0.56.0 It is poorly designed, specific to GitHub's CommonMark transition of 2017, and should not be used.

Comrak additionally supports its own extensions, which are in the process of being specced out (join the effort!):

  • Alerts
  • Attributes
  • Block directives
  • CJK friendly emphasis (tats-u/markdown-cjk-friendly)
  • Description lists
  • Emoji shortcodes
  • Footnotes
  • Front matter
  • Greentext
  • Grid tables
  • Header IDs
  • Highlight
  • Inline footnotes
  • Insert
  • Math
  • Multi-line blockquotes
  • Obsidian block IDs
  • Obsidian callouts
  • Obsidian comments
  • Phoenix HEEx
  • Spoiler text
  • Subscript
  • Subtext
  • Superscript
  • Underline
  • Wikilinks

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

Custom formatting

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.

Plugins

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

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.

Related projects

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:

  • 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 looks really promising.
  • markdown-it is a port of JavaScript's markdown-it.js.
  • babelmark lets you compare many implementations at once, including the above.
  • Know of another library? Please open a PR to add it!

Bindings

  • Commonmarker — Ruby bindings for this library built with Magnus/rb-sys. Available on RubyGems as commonmarker.
  • MDEx — Elixir bindings for this library built with Rustler. Available on Hex as mdex.
  • comrak — Python bindings for this library built with PyO3. Available on PyPI as comrak, benchmarked at 15-60x faster than pure Python alternatives.
  • comrak-ext — Python bindings; fork of comrak with additional APIs exposed, including the AST. Available on PyPI as comrak-ext.
  • comrak-wasm — TypeScript bindings for this library, built with WebAssembly. Available on npm as comrak and JSR as @nick/comrak.
  • @jeremy-code/comrak-wasm — JavaScript bindings for this library built with WebAssembly. Available on npm as comrak-wasm.

Users

Comrak is used in a few Rust-y places, and more beyond:

  • crates.io, docs.rs and lib.rs use Comrak to render README Markdown faithfully.
  • GitLab uses Comrak to render Markdown documents, work items, merge requests, notes, and more.
  • Deno uses Comrak to render documentation in deno_doc.
  • Reddit's new-style site uses a Comrak fork1.
  • Lockbook is a Markdown-based secure notebook with native apps. It looks really neat!!
  • Markview is a fast, native Markdown reader with publication-quality typography. It's mostly Obsidian compatible.
  • many more!

I'd be really happy to add your site or app here, just open a PR or issue. :)

Benchmarking

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-comrak

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.

make bench-all

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

Stability guarantees

Regular SemVer 2.0.0 applies to our Rust API. Beyond that, you can expect the following.

Patch releases:

  • Output changes: incorrect output (bugs, like a missing symbol or something), incorrect sourcepos, anything that results in a crash, a hang, or a security issue (e.g. dangerous_url tightening). If there was any way we weren't compatible with the current CommonMark target (and it'd have to be a textual interpretation issue, as we're always passing the executable spec), that'd be a bug and also come in here.
  • MSRV bumps: never.
  • #[doc(hidden)] items: may change.
  • Option defaults: never.
  • Cargo features: never.
  • CLI bits and pieces (arguments, exit codes, config file format, stdin/stdout): never.

Minor releases:

  • Output changes: new output from a new option or extension; upgrading to a new CommonMark version. Since we're writing our own specs, we don't intend to try to be compatible with any changes a future GFM spec may bring --- not that we anticipate any. We remain executably compatible with it as it stands at 0.29-gfm.
  • Comrak spec changes where new examples are added may fall in patch or minor releases, depending on their nature.
  • Any option or extension currently without a complete write-up per #924 is liable to change output in the minor version it gets its spec! It'll probably be in very edge-case-y ways you might never have run into, but be warned.
  • MSRV bumps: can happen, always at least 6 months old.
  • #[doc(hidden)] items: may change.
  • Option defaults: never.
  • Cargo features: adding a feature, or adding to an existing one.
  • CLI bits and pieces: flags might get added, additional selections might get added to existing flags (e.g. --extension, --list-style); nothing else.

Major releases:

  • Output changes: literally anything else.
  • This includes Comrak spec changes where an existing example is changed.
  • MSRV bumps: can happen.
  • #[doc(hidden)] items: may change.
  • Option defaults: may change.
  • Cargo features: may change.
  • CLI bits and pieces: may change.
  • It's like Web 2.0 but for Comrak.

API deprecations will be flagged in a minor release, to be removed in the next major.

Note that each output format also has its own nuances:

  • Comrak's AST is kind of the ur-output format, and the above applies to it. For a given set of options, you expect to see the same kinds of node types and where they nest. It won't change in patch releases (unless clearly a bug), and may change in minor releases with new options/extensions, CommonMark upgrades, or added Comrak spec examples.
  • HTML has the CommonMark spec and Comrak's fixture-based docs. If there's edge cases the docs don't cover, then I think they're bugs if they don't make sense in light of the documented intent, and fixing them (and documenting them!) isn't a breaking change. Changing things like class names and data- attributes is breaking.
  • CommonMark is promised to re-parse to the same AST, but not necessarily beyond that. A Strong node may be output as __strong__ today and **strong** tomorrow under default options and I wouldn't call that breaking. Your code block may come out with a different length fence, so long as it means the same thing.
  • XML will always have the same element and attribute names, but who knows, maybe I'll start interior-spacing all the tags < like / > < this / >. I won't, but I might be lying.

Contributing

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.

I practice Optimistic Merging as described by Peter Hintjens, where possible, and respecting our stability guarantees. Please keep the code of conduct in mind too.

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

Vulnerabilities

Please report security issues to the author at <ashe@kivikakk.ee>. If you have a GitHub account, you are welcome to use its interface to privately report security issues.

Policy on LLM contributions

Please do not submit the output of LLMs to Comrak, in any form. For example, do not use them to:

  • Write code.
  • Write tests.
  • Write comments.
  • Write issue or pull request descriptions.
  • Write documentation.

This list isn't exhaustive, and skirting the rules is not tolerated.

If an LLM has played a part in your discovery of a bug, or performance or security issue, that's OK — I simply ask that you write the issue, fix, or pull request description yourself, by hand. If you do not personally understand what you have submitted, you are assisting neither Comrak's maintainers nor yourself with your submission.

I make an exception for vulnerability reports. If you've found a legitimate security issue in Comrak, you may privately submit an LLM-written report. If, however, your reports are consistently trash tier, I will block you from the project. There's no reason they have to be. This hasn't happened, yet, and (a) I am grateful, and (b) don't be the first. I will update this canary should this fact ever change.

Contributors

Small chart showing Comrak contributors.

Contact

Asherah Connor <ashe@kivikakk.ee>

Legal

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.

Footnotes

  1. 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. ↩

About

CommonMark + GFM compatible Markdown parser and renderer

Resources

Code of conduct

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages