Comrak for CommonMark and GFM rendering in Rust

Comrak's CommonMark-first parsing boundary

Comrak addresses applications that need to turn untrusted or user-authored Markdown into HTML, XML, or normalized CommonMark. Its intended users are Rust developers embedding a parser in an application, as well as command-line users who want configurable conversion without writing a wrapper script. The library is not limited to GitHub's dialect. According to the README and `Cargo.toml`, it is compliant with CommonMark 0.31.2 by default, while GFM behavior is enabled separately.

That separation matters because parsing rules affect links, emphasis, HTML handling, task lists, tables, and extension syntax. A project that expects CommonMark output may not want GitHub-specific interpretation, while a GitHub compatibility target may need tables, autolinks, strikethrough, task lists, and GFM rendering quirks. Comrak exposes those as named switches rather than burying one fixed dialect in the default parser.

The CLI describes itself as a CommonMark-compatible GitHub Flavored Markdown parser and formatter. It accepts one or more files, or standard input when no file is passed. Its output can be HTML, XML, or CommonMark. This makes it useful for static-site pipelines, documentation checks, Markdown normalization, and service code that needs more control over parsing and rendering than a line-oriented converter can offer. The repository also includes example programs for custom formatters, alternate text, heading customization, AST traversal, syntax highlighting, and an S-expression renderer. Those files indicate that Comrak is intended to be adapted rather than used only as a black-box command.

Parsing options, extensions, and output flow

The documented CLI flow is direct: Comrak parses input files or standard input, applies the selected configuration, and writes the requested representation. HTML is the default output. XML and CommonMark are available through `--to`, while `--output` redirects the result to a file. The parser can retain source locations through `--sourcepos`, and `--sourcepos-chars` changes column reporting from UTF-8 byte offsets to Unicode character counts.

GFM support is concrete but optional. `--gfm` enables strikethrough, tables, autolinks, and task lists. It also activates `--github-pre-lang` and `--gfm-quirks`, which changes code block language markup and adopts GFM-specific HTML behavior. Individual extensions can instead be selected with `--extension` or `-e`, including `footnotes`, `description-lists`, `math-dollars`, `wikilinks-title-after-pipe`, `underline`, `subscript`, `spoiler`, `alerts`, `block-directive`, and several attribute extensions. This is preferable to assuming that every optional syntax feature follows GitHub behavior.

Raw HTML creates a separate policy decision. The CLI defaults to avoiding ordinary inline and block HTML, while `--unsafe` permits it. The `--escape` option escapes raw HTML and takes precedence over `--unsafe`. `--escaped-char-spans` can also wrap escaped Markdown characters in a `data-escaped-char` span. Services that render user content should therefore review more than parser conformance. They need to decide which extensions are enabled, whether links can be relaxed, and how raw HTML is handled.

The package dependencies reflect document-processing concerns such as arena-backed storage, Unicode character recognition, small-vector storage, hashing, and entity generation. The repository layout also contains fuzzing, benchmarks, and many examples. Those files do not establish any specific throughput result, but they show that parser construction, conformance, formatting, and document-tree manipulation are separate areas maintained by the project.

Installing Comrak and checking the CLI

For a Rust application, add the documented crate requirement to `Cargo.toml`. The library supports Rust 1.89 or later.

[dependencies]
comrak = "0.56"

After adding the dependency, Cargo can resolve the library for the application. The package version in `Cargo.toml` is 0.56.0, while the README uses the compatible minor release line `0.56`.

For a standalone executable on a machine with a Rust toolchain, the README lists this installation command:

cargo install comrak

The README also documents `cargo bininstall comrak`, package-manager installations, and GitHub Releases binaries. Its installation note specifically says that published builds are limited to machines available to the maintainer at build time. Users who require reproducible or platform-specific builds should account for that constraint.

A first check is the complete command-line help, which documents accepted files, output formats, extension names, and HTML policy flags:

comrak --help

This should print the CLI usage text, including `[FILE]...` as the input argument and `html`, `xml`, and `commonmark` as output choices. For an initial file conversion, the documented argument model means this command passes `README.md` as input and writes the default HTML representation to standard output:

comrak README.md

The precise rendered result depends on that file and the active configuration. Raw HTML in the input is particularly important to inspect because `--unsafe` and `--escape` produce different security-related behavior.

Embedding Comrak and customizing the document tree

The dependency declaration provides access to the library, but the README does not include a complete Rust API example. It identifies the official documentation at `docs.rs` and points to example source files under `examples/`. For an engineer embedding Comrak, those are the relevant places to inspect before designing the integration.

The example filenames reveal several extension points. `custom_formatter.rs` indicates configurable rendering, while `custom_formatter_alt_text.rs` points to alternative text as a specific customization concern. `custom_headings.rs` and `headers.rs` target heading generation, and `traverse_demo.rs` indicates AST traversal. The repository also includes a custom syntax highlighter and a Syntect example, while the CLI exposes `--syntax-highlighting` with CSS classes, a theme name, or `none`.

This separation can be useful when output requirements exceed string replacement. An application can format different node types according to its own policies, add metadata to rendered elements, traverse the parsed document, or select syntax-highlighting behavior. However, the README does not publish the formatter trait signatures or the exact AST APIs. An implementation should use the versioned `docs.rs` documentation and the checked-out examples rather than assume API names or types.

Feature selection also affects the dependency footprint. The default feature list includes `cli`, `syntect-onig`, and `bon`, while several dependencies are optional. `Cargo.toml` defines additional features for library consumers. A server that does not need the command-line interface should review the complete feature list before deciding whether default features are appropriate. The README does not provide a reduced-feature installation command, so one should not be inferred from the partially displayed `Cargo.toml`.

GFM differences, raw HTML, and extension trade-offs

Comrak is a poor fit for a service that treats every Markdown document as GFM without considering context. GFM mode changes both syntax recognition and output behavior. It adds four named extensions and activates GitHub-style code block language markup and GFM quirks. Applications that compare output against another Markdown implementation may need to align those switches deliberately, because default CommonMark output and GFM output are not interchangeable.

The autolink controls illustrate another boundary. `--relaxed-autolinks` allows bracketed link recognition, all URL schemes, and domains without a TLD such as `http://localhost`. That behavior can be necessary for internal documentation, but it also broadens what the parser accepts. The README does not define an application-level URL validation policy, so consumers must not treat automatic link recognition as a security check.

Raw HTML has a genuine failure mode for rendering pipelines. Permitting it with `--unsafe` passes inline and block HTML through, while `--escape` neutralizes it and takes precedence. Services that sanitize output elsewhere, apply a strict content-security policy, or promise that rendered comments contain no submitted HTML need to document which mode they use. Comrak controls Markdown parsing and HTML generation. The README does not establish that Comrak performs general sanitization for links, images, attributes, or every generated URL.

CommonMark round trips also have limits. The formatter can optimize escapes with `--experimental-minimize-commonmark`, but that option is explicitly experimental and described as using a trial-and-error algorithm. Input formatting can alter source presentation while retaining parsed meaning. Projects that treat Markdown as an exact source format should compare parsed output before adopting the formatter.

Comrak versus a fixed GFM renderer

A fixed GFM renderer is the clearest alternative for an application whose only requirement is to reproduce one dialect. Such a renderer can select compatibility settings once and avoid exposing parser policy to each caller. It may also be easier to deploy if the application already depends on a JavaScript Markdown implementation or a C library available through operating-system packages.

Comrak takes a different approach. It keeps CommonMark 0.31.2 as the library default, activates GFM through named options, and allows extensions to be selected independently. Its CLI can emit HTML, XML, or normalized CommonMark rather than only HTML. The repository examples also expose formatter and traversal customization, which is useful when an application needs to control output beyond the dialect. The trade-off is that integrators must make more policy decisions and must preserve those decisions across versions.

The `Makefile` includes benchmark targets for `cmark-gfm`, `pulldown-cmark`, and `markdown-it`, but the repository files do not publish corresponding benchmark results. Those targets show that comparative evaluation is part of the development workflow, not evidence that Comrak is faster than any alternative. Selection should therefore depend on dialect requirements, output control, deployment constraints, and licensing requirements rather than an unsupported performance assumption.

Comrak releases, Rust requirements, and licensing

Comrak is not archived, and the last push was on 2026-10-15. The recent release history includes v0.56.0 on 2026-10-06, v0.55.0 on 2026-09-06, and v0.54.0 on 2026-07-12. That release cadence shows recent activity, although it does not by itself guarantee compatibility for every consumer.

The current package requires Rust 1.89 and uses Rust edition 2024. This is the clearest upgrade constraint stated by the project. Applications pinned to an older Rust toolchain cannot adopt the current release without also changing or upgrading that toolchain. Because Comrak is a library, upgrades can affect command-line features and extensions. The version-specific `CHANGELOG.md` is the appropriate source for determining those changes.

Licensing metadata needs careful review. The repository description classifies the license as a custom license that GitHub cannot classify and points to the `LICENSE` file, while `Cargo.toml` declares `BSD-2-Clause`. This review is not legal advice. Before redistribution, an organization should inspect the actual `LICENSE` file and confirm that its terms match the package metadata expected by its dependency and compliance processes. The presence of `COPYING` is visible in the repository, but the README does not explain its contents, so no additional licensing obligation should be assumed from the filename alone.

Editorial conclusion

Developers should adopt Comrak when their Rust service needs CommonMark-first parsing with explicit extension controls or Markdown round trips. It is a poor fit when an always-on GFM interpretation is mandatory or when native support below Rust 1.89 is required. Before adoption, inspect the `LICENSE` file alongside the `BSD-2-Clause` package metadata, then verify that the selected extension and HTML safety settings match the application's input policy.

Frequently asked questions

Official sources

1. Issues
2. kivikakk/comrak on GitHub
3. Project website
4. README
5. Releases