mity/md4c: A Callback-Based Markdown Parser for C Applications

Why mity/md4c targets C application parsers

mity/md4c solves a specific integration problem: adding Markdown processing to a C application without first adopting a large document model or a dependency-heavy parser stack. The README positions it as a production-quality parser for applications that process Markdown but do not need a large document tree. Its primary audience is therefore developers embedding Markdown in editors, desktop applications, document tools, rendering systems, and other software that already has its own output format.

The project is written in C and has no third-party dependencies. The core parser consists of `md4c.c` and `md4c.h`, so an application can link MD4C as a library or compile those files directly into its own codebase. That choice matters in environments where dependency packaging, static linking, source distribution, or build-system control is important. It does not provide a complete Markdown application by itself. It provides the parsing layer and lets the host application decide what the parse events mean.

The README also states that MD4C passes the compliance tests for CommonMark specification 0.31.2. That establishes a specification target, but it does not mean that every Markdown dialect is enabled. The default behavior recognizes syntax defined by CommonMark, while additional behavior requires explicit flags. The project therefore offers a predictable compatibility boundary rather than silently accepting every extension encountered in the wild.

The md_parse() callback architecture

The central API is `md_parse()`. It accepts Markdown text and a structure containing pointers to callbacks. Instead of returning a complete tree of block and span objects, MD4C processes the complete document and informs the application through callbacks. The callbacks report the start and end of Markdown blocks, the start and end of spans, and textual content.

This push model places rendering responsibility in the consumer. An application can use those events to produce HTML, a custom document representation, screen output, or another target format. The callback stream also means that the host does not need to retain every parsed construct as a separate in-memory object. That is the main architectural difference from parsers centered on returning a materialized syntax tree.

The tradeoff is that the application must implement the callbacks correctly. A renderer needs to maintain state while entering and leaving nested constructs, write text as it arrives, and decide how unsupported or extension-specific constructs should be represented. MD4C supplies the parsing decisions, but it does not automatically solve output escaping, semantic interpretation, or application-specific rendering policy.

The README describes the API as very straightforward and says there is actually just one function, `md_parse()`. That is a useful simplification, but it should not be read as meaning that the callback protocol is trivial. Event order, nesting, text handling, and renderer behavior still form the integration surface.

Extensions and CommonMark compatibility flags

MD4C keeps compatibility configurable through flags. The README lists GitHub-style admonitions, whitespace collapsing, footnotes, hard line breaks, highlighting, insertion, LaTeX math spans, permissive ATX headers, and permissive email and URL autolinks. Each feature has a named `MD_FLAG_...` option, so an application can decide whether its Markdown corpus should follow strict CommonMark behavior or accept syntax commonly found in GitHub-oriented documents.

Footnotes have a defined output policy. With `MD_FLAG_FOOTNOTES`, references and definitions such as `[^note]` are supported, and referenced definitions are emitted at the end of the document in first-reference order. That detail matters to renderers because footnote collection is not necessarily equivalent to preserving definition order from the source file.

The math option has an important limitation in the HTML path. With `MD_FLAG_LATEXMATHSPANS`, the parser recognizes inline and display math delimiters, but the documented HTML renderer emits the content verbatim in a custom `<x-equation>` tag. Applications requiring a particular math layout, sanitization policy, or MathML conversion will need additional renderer logic.

These flags are useful because they make dialect differences visible in the calling code. They also create testing obligations. Enabling an extension changes the accepted document language and can change renderer events, so the selected flag set should be treated as part of an application's compatibility contract.

Installing md4c and making a first parser call

The README does not provide a package-manager installation recipe. It says to include `md4c.h` and link against the MD4C library, or alternatively add `md4c.c` and `md4c.h` directly to the codebase. The documented library link flag is:

-lmd4c

That flag identifies the MD4C library at link time. The README does not document a complete `cmake`, `make`, or package installation command, so this article does not invent one. The repository layout does include `CMakeLists.txt`, source files under `src/`, and test-related files under `test/`, but the README does not give the exact build invocation for those entries.

For the first use, the application includes `md4c.h`, prepares a callback structure, and calls `md_parse()` with the Markdown input. The callbacks should handle block and span boundaries and append textual content to the application output. The expected result is not a returned HTML string or document tree. It is a sequence of parser events delivered to the supplied callbacks.

If HTML is the target, the README documents a higher-level conversion path. Include `md4c-html.h`, link against the MD4C-HTML library using the documented `-lmd4c-html` option, and call `md_html()`. Its callback receives chunks of HTML output, which can be appended to a buffer or written to a file.

Encoding, portability, and operational limits

MD4C expects UTF-8 by default. The README describes two compile-time alternatives: an ASCII-only control-character mode that disables Unicode-specific code, and, on Windows, UTF-16 input, described as what Windows commonly calls Unicode. These are build and input-contract choices, not automatic runtime encoding detection. An application accepting documents from several sources must establish how bytes are decoded before passing them to the parser.

The project states that it builds and works on Windows and POSIX-compliant operating systems. It also notes that a heap memory interface is part of the practical portability requirement. The README does not document compiler versions, feature-test macros, supported architectures, or a complete matrix of build configurations. Consequently, portability claims should be checked against the application's actual compiler and platform settings rather than inferred from the list of operating systems.

MD4C is described as designed for hostile input, meaning Markdown received from users who did not author the documents. That design goal is relevant for parsers exposed to untrusted content, but the README does not claim that the surrounding application is secure by default. Rendering, URL handling, HTML escaping, resource limits, and policy decisions may still belong to the host application. The parser's resistance to pathological parsing behavior does not remove the need to review the complete rendering path.

MD4C compared with a document-tree Markdown parser

The closest architectural alternative is a Markdown parser that returns a materialized document tree. Such a parser can be convenient when the application needs random access to nodes, repeated traversal, editing operations, or a generic syntax representation. The host does not have to implement a renderer around callback events, and tree-oriented code may be easier for some document-processing workflows.

MD4C takes the opposite approach. It keeps the parser compact and exposes events as the document is processed. That can suit applications that already own their rendering model or want to avoid retaining a full parse result. It also makes the contract explicit: the application supplies callbacks and decides what to do with each event.

The choice is not simply parser versus parser. A tree-based library may solve document editing and traversal more directly. MD4C may fit a streaming or custom-rendering pipeline and can be embedded as two source files. The README does not claim that MD4C supplies editing APIs, a complete HTML document, or a higher-level Markdown application, so those needs require separate assessment.

Maintenance, licensing, and adoption costs

The repository is not archived, and the last push was on 2026-10-13. The README describes MD4C as independently maintained open-source software. It says sponsorship supports specification compliance, compiler and platform compatibility, extensions, performance and memory-efficiency work, testing, fuzzing, documentation, tooling, and contribution review. The repository has no GitHub releases listed, so consumers should not expect release information to be available from GitHub Releases.

The code is licensed under the MIT license. The README characterizes this as permissive, which means applications can generally incorporate the library subject to the license terms. This article does not provide legal advice, and the actual `LICENSE.md` should be reviewed for the project's exact obligations and notice requirements.

The principal adoption cost is integration work. MD4C has a small source footprint, but the callback-based API still requires careful renderer implementation. An application may also need to decide which extensions to enable, select an input encoding policy, handle unsupported constructs, and test the behavior of its own output callbacks. Maintenance is not limited to upgrading the parser. Changes in accepted Markdown syntax or renderer assumptions can require application tests.

Editorial conclusion

Adopt mity/md4c when a C application needs direct Markdown parsing, limited dependencies, and control over rendering callbacks. Do not choose it when a ready-made application, a complete document tree, or a broad third-party ecosystem matters more than a compact parser. Verify first that your required Markdown extensions, input encoding, renderer callbacks, and platform build expectations fit the documented API.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mity/md4c on GitHub
4. README