cmark — Overview

What Is cmark?

cmark is a C library and command-line tool for parsing and rendering CommonMark (standardized Markdown). Written in C99, it implements a two-phase parsing architecture — block structure recognition followed by inline content parsing — producing an Abstract Syntax Tree (AST) that can be traversed, manipulated, and rendered into multiple output formats.

Language: C (C99)
Build System: CMake (minimum version 3.14)
Project Version: 0.31.2
License: BSD-2-Clause
Authors: John MacFarlane, Vicent Marti, Kārlis Gaņģis, Nick Wellnhofer

Core Architecture Summary

cmark's processing pipeline follows this sequence:

1. Input — UTF-8 text is fed to the parser, either all at once or incrementally via a streaming API.
2. Block Parsing (blocks.c) — The input is scanned line-by-line to identify block-level structures (paragraphs, headings, code blocks, lists, block quotes, thematic breaks, HTML blocks).
3. Inline Parsing (inlines.c) — Within paragraph and heading blocks, inline elements are parsed (emphasis, links, images, code spans, HTML inline, line breaks).
4. AST Construction — A tree of cmark_node structures is built, with each node representing a document element.
5. Rendering — The AST is traversed using an iterator and rendered to one of five output formats: HTML, XML, LaTeX, man (groff), or CommonMark.

Source File Map

The cmark/src/ directory contains the following source files, organized by responsibility:

Public API

AST Node System

Parsing

Traversal

Renderers

Text Processing and Utilities

The Simple Interface

The simplest way to use cmark is a single function call defined in cmark.c:

char *cmark_markdown_to_html(const char *text, size_t len, int options);

Internally, this calls cmark_parse_document() to build the AST, then cmark_render_html() to produce the output, and finally frees the document node. The caller is responsible for freeing the returned string.

The implementation in cmark.c:

char *cmark_markdown_to_html(const char *text, size_t len, int options) {
  cmark_node *doc;
  char *result;

  doc = cmark_parse_document(text, len, options);
  result = cmark_render_html(doc, options);
  cmark_node_free(doc);

  return result;
}

The Streaming Interface

For large documents or streaming input, cmark provides an incremental parsing API:

cmark_parser *parser = cmark_parser_new(CMARK_OPT_DEFAULT);

// Feed chunks of data as they arrive
while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) {
    cmark_parser_feed(parser, buffer, bytes);
}

// Finalize and get the AST
cmark_node *document = cmark_parser_finish(parser);
cmark_parser_free(parser);

// Render to any format
char *html = cmark_render_html(document, CMARK_OPT_DEFAULT);
char *xml  = cmark_render_xml(document, CMARK_OPT_DEFAULT);
char *man  = cmark_render_man(document, CMARK_OPT_DEFAULT, 72);
char *tex  = cmark_render_latex(document, CMARK_OPT_DEFAULT, 80);
char *cm   = cmark_render_commonmark(document, CMARK_OPT_DEFAULT, 0);

// Cleanup
cmark_node_free(document);

The parser accumulates input in an internal line buffer (parser->linebuf) and processes complete lines as they become available. The S_parser_feed() function in blocks.c scans for line-ending characters (\n, \r) and dispatches each complete line to S_process_line().

Node Type Taxonomy

cmark defines 21 node types in the cmark_node_type enum:

Block Nodes (container and leaf)

Inline Nodes

Range sentinels are also defined for classification:

• CMARK_NODE_FIRST_BLOCK = CMARK_NODE_DOCUMENT
• CMARK_NODE_LAST_BLOCK = CMARK_NODE_THEMATIC_BREAK
• CMARK_NODE_FIRST_INLINE = CMARK_NODE_TEXT
• CMARK_NODE_LAST_INLINE = CMARK_NODE_IMAGE

Option Flags

Options are passed as a bitmask integer to parsing and rendering functions:

#define CMARK_OPT_DEFAULT       0
#define CMARK_OPT_SOURCEPOS     (1 << 1)   // Add data-sourcepos attributes
#define CMARK_OPT_HARDBREAKS    (1 << 2)   // Render softbreaks as hard breaks
#define CMARK_OPT_SAFE          (1 << 3)   // Legacy (now default behavior)
#define CMARK_OPT_NOBREAKS      (1 << 4)   // Render softbreaks as spaces
#define CMARK_OPT_NORMALIZE     (1 << 8)   // Legacy (no effect)
#define CMARK_OPT_VALIDATE_UTF8 (1 << 9)   // Validate UTF-8 input
#define CMARK_OPT_SMART         (1 << 10)  // Smart quotes and dashes
#define CMARK_OPT_UNSAFE        (1 << 17)  // Allow raw HTML and dangerous URLs

Memory Management Model

cmark uses a pluggable memory allocator defined by the cmark_mem struct:

typedef struct cmark_mem {
  void *(*calloc)(size_t, size_t);
  void *(*realloc)(void *, size_t);
  void (*free)(void *);
} cmark_mem;

The default allocator in cmark.c wraps standard calloc/realloc/free with abort-on-NULL safety checks (xcalloc, xrealloc). Every node stores a pointer to the allocator it was created with (node->mem), ensuring consistent allocation/deallocation throughout the tree.

Version Information

Runtime version queries:

int cmark_version(void);               // Returns CMARK_VERSION as integer (0xMMmmpp)
const char *cmark_version_string(void); // Returns CMARK_VERSION_STRING

The version is encoded as a 24-bit integer where bits 16–23 are major, 8–15 are minor, and 0–7 are patch. For example, 0x001F02 represents version 0.31.2.

Backwards Compatibility Aliases

For code written against older cmark API versions, these aliases are provided:

#define CMARK_NODE_HEADER      CMARK_NODE_HEADING
#define CMARK_NODE_HRULE       CMARK_NODE_THEMATIC_BREAK
#define CMARK_NODE_HTML        CMARK_NODE_HTML_BLOCK
#define CMARK_NODE_INLINE_HTML CMARK_NODE_HTML_INLINE

Short-name aliases (without the CMARK_ prefix) are also available unless CMARK_NO_SHORT_NAMES is defined:

#define NODE_DOCUMENT    CMARK_NODE_DOCUMENT
#define NODE_PARAGRAPH   CMARK_NODE_PARAGRAPH
#define BULLET_LIST      CMARK_BULLET_LIST
// ... and many more

Cross-References

• architecture.md — Detailed two-phase parsing pipeline, module dependency graph
• public-api.md — Complete public API reference with all function signatures
• ast-node-system.md — Internal cmark_node struct, type-specific unions, tree operations
• block-parsing.md — blocks.c line-by-line analysis, open block tracking, finalization
• inline-parsing.md — inlines.c delimiter algorithm, bracket stack, backtick scanning
• iterator-system.md — AST traversal with enter/exit events
• html-renderer.md — HTML output with escaping and source position
• xml-renderer.md — XML output with CommonMark DTD
• latex-renderer.md — LaTeX output via render framework
• man-renderer.md — groff man page output
• commonmark-renderer.md — Round-trip CommonMark output
• render-framework.md — Shared cmark_render() engine for text-based renderers
• memory-management.md — Allocator model, buffer growth, node freeing
• utf8-handling.md — UTF-8 validation, iteration, case folding
• reference-system.md — Link reference definitions storage and resolution
• scanner-system.md — re2c-generated pattern matching
• building.md — CMake build configuration and options
• cli-usage.md — Command-line tool usage
• testing.md — Test infrastructure (spec tests, API tests, fuzzing)
• code-style.md — Coding conventions and naming patterns