cmark
Render Markdown to HTML or other formats
TLDR
Render a CommonMark Markdown file to HTML
Convert data from stdin to LaTeX
Convert straight quotes to smart quotes
Validate UTF-8 characters
SYNOPSIS
cmark [OPTIONS] [FILE...]
PARAMETERS
-t, --to FORMAT
Specify the desired output format. Common formats include html, xml, commonmark (for re-rendering), man, latex, and plaintext.
-p, --safe
Disable unsafe extensions, such as raw HTML blocks and autolinks, to enhance security when processing untrusted input.
-e, --extension EXT
Enable specific extensions (e.g., table, strikethrough, autolink, tasklist). This option can be specified multiple times.
-o, --output FILE
Direct the processed output to the specified FILE instead of standard output.
-V, --version
Display the version information of cmark and exit.
-h, --help
Show the help message and exit, detailing available options and usage.
--source-pos
Include source position attributes in the output (e.g., as data attributes in HTML), useful for debugging or linking back to original source.
--hardbreaks
Render newline characters within paragraphs as hard line breaks (<br> in HTML) instead of spaces.
--nobreaks
Render newline characters within paragraphs as spaces, even if they would otherwise be treated as hard breaks.
--validate-utf8
Validate that the input text is valid UTF-8. If invalid bytes are encountered, an error will be reported.
--smart
Enable smart punctuation, converting straight quotes to curly quotes, --- to em-dashes, -- to en-dashes, and ... to ellipses.
--width WIDTH
Specify the preferred line width for certain output formats like man pages or plaintext, aiding readability.
--warn-bare-urls
Issue warnings about bare URLs. Note: this option is deprecated and may be removed in future versions.
DESCRIPTION
cmark is the reference C implementation of CommonMark, a highly specified and unambiguous dialect of Markdown. It serves to parse CommonMark-formatted text and render it into various output formats, including HTML, XML, man pages, LaTeX, and plaintext. Its primary goal is to provide a consistent and predictable Markdown parsing experience, addressing the ambiguities present in earlier, less defined Markdown implementations. It can process input from one or more files or standard input, writing the result to standard output or a specified file.
CAVEATS
cmark strictly adheres to the CommonMark specification. This means it may not support all the non-standard extensions found in other Markdown flavors (like GitHub Flavored Markdown) unless explicitly enabled via the --extension option. Its primary focus is on correctness and consistency, not on supporting every possible Markdown syntax variation by default. The --warn-bare-urls option is deprecated.
LIBRARY USAGE
In addition to being a command-line tool, cmark is also distributed as a C library (libcmark). This library can be integrated into other applications to provide robust CommonMark parsing and rendering capabilities, making it a foundational component for many Markdown-aware software projects.
COMMONMARK SPECIFICATION
cmark's behavior is precisely defined by the CommonMark Specification. This specification provides an unambiguous description of Markdown's syntax, including a comprehensive suite of thousands of test cases. This adherence ensures that cmark's output for a given CommonMark input is consistent across different environments and versions.
HISTORY
The CommonMark specification was created to address the long-standing problem of Markdown's ambiguities, which led to incompatible implementations. cmark is the reference C implementation of this specification, developed to provide a standard and predictable parsing and rendering engine. It was initially developed by John MacFarlane and others as part of the CommonMark initiative, aiming to bring consistency and a rigorous test suite to the Markdown ecosystem. Its development focuses on strict compliance with the spec and high performance.