LinuxCommandLibrary

cmark

Render Markdown to HTML or other formats

TLDR

Render a CommonMark Markdown file to HTML

$ cmark --to html [filename.md]
copy

Convert data from stdin to LaTeX
$ cmark --to latex
copy

Convert straight quotes to smart quotes
$ cmark --smart --to html [filename.md]
copy

Validate UTF-8 characters
$ cmark --validate-utf8 [filename.md]
copy

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.

SEE ALSO

pandoc(1), markdown(1)

Copied to clipboard