Native Markdown tools written in C11 that share one small, dependency-free parser:
- md-printer: renders a Markdown file and hands it to the operating system's own print dialog (Windows, macOS, Linux).
- md-reader: a terminal pager for Markdown (Linux/macOS).
The shared parser passes 612 of 652 (93.9%) of the official CommonMark 0.31.2 spec examples, and runs clean under AddressSanitizer and UBSan across the whole spec corpus.
mdtools began as a tool I wanted — printing a Markdown file without a browser in the way — and became the project where I worked out how to direct AI coding agents with a process I would trust.
Nearly all of the code and documentation was written by AI agents under my direction. Claude
(Anthropic) wrote the parser, both tools and most of the documentation; Codex (OpenAI) wrote the
governance and compliance layer. Most commits say so in Co-Authored-By trailers. The commits I
typed myself are few: the early Windows duplex work and a couple of line-ending fixes.
My part was the process around the agents:
- most changes landed as pull requests, each reviewed and merged by me; a dozen smaller commits —
the earliest work, some documentation, and the 0.3.0 cut — went straight to
main; - written decisions for architectural choices (docs/DECISIONS.md);
- checks tested by planting the defect they exist to catch, and a ledger
(docs/COMPLIANCE.md) recording which ones have been made to fail and which
have not. The sanitizer run, the spec ratchet, the corpus pin, the pathological-input guard and
make checkitself have been; cppcheck, clang-tidy and the compiler builds are still marked "not yet".
Planting failures found real problems in the checks themselves. The sanitizer run reported PASS on
a planted heap overflow, because the test runner discarded the child process's stderr. The
pathological-input guard reported PASS for a binary that failed all 26 of its cases, because it
only measured elapsed time. Both are fixed; see commits
b4deae2 and
d3c7968.
The instructions the agents work under are in AGENTS.md; who may approve, merge and release is in GOVERNANCE.md.
| Component | State |
|---|---|
Parser (core/) |
93.9% CommonMark; sanitizer-clean; guarded against super-linear blow-ups on hostile input |
| md-printer | Builds on Linux (GTK 3), Windows (MSVC and MinGW-w64) and macOS (Cocoa). Tables, duplex. No macOS CI runner |
| md-reader | Linux/macOS (ncurses). No Windows console backend |
| Latest release | 0.3.0 (see CHANGELOG.md) |
| Activity | Paused since August 2026. The next milestone is planned in docs/V0.4-PLAN.md but not started |
- Two parsers, two feature sets. The spec-compliant tree parser (
md_parse_ast) handles nested containers but not GFM tables. md-printer and md-reader still use the older flat parser (md_parse), which handles tables but flattens nesting. A quote inside a list item, or a second paragraph in a list item, prints un-nested. Moving both tools onto the tree is v0.4. - A known emphasis bug. The "rule of three" compares the delimiter lengths that remain rather
than the original ones, so
*a***b*renders as<em>a</em>**b*where CommonMark calls for<em>a</em>*<em>b</em>. All 132 emphasis examples in the spec suite pass; a differential test against cmark found it anyway. The fix is understood and not yet applied. - HTML output is not safe for untrusted input.
core/html.cexists to measure spec compliance. Like the spec, it passes raw HTML andjavascript:links through unchanged. - Remaining spec gaps are mostly tabs (64%), named entities (50 common names, not HTML5's roughly 2,000), and link edge cases (86%).
- No bare-URL autolinking, footnotes, or math.
Linux. On Fedora, install:
sudo dnf install make gcc gtk3-devel ncurses-devel pkgconf-pkg-config.
On Debian/Ubuntu, install:
sudo apt install build-essential pkg-config libgtk-3-dev libncurses-dev.
Then:
make # builds build/md-printer and build/md-reader
./build/md-reader README.md
./build/md-printer README.md # opens the system print dialogmacOS: xcode-select --install, then make.
Windows: run build.bat. It needs Visual Studio with the "Desktop development with C++"
workload and finds the compiler itself. This produces build\md-printer.exe only.
md-printer [--duplex[=long|short] | --simplex] [file.md] # no file: native file picker
md-reader [-p] <file.md> # or: cat file.md | md-reader
In md-reader: q quits, j/k scroll, space/b page, g/G go to the top or end, and
/, n and N search.
One command runs every check locally and in CI, and writes build/check-report.txt:
format (clang-format) · cppcheck · clang-tidy · strict -Werror build · parser golden test ·
the same under ASan+UBSan · reader layout golden test · reader driven through a pseudo-terminal ·
CommonMark suite · CommonMark suite under ASan+UBSan · pathological-input timing guard ·
internal doc links · executable bits on tracked scripts
# Fedora: sudo dnf install make gcc clang clang-tools-extra cppcheck gtk3-devel ncurses-devel \
# pkgconf-pkg-config python3 libasan libubsan git
make check SPEC_ALLOW_FETCH=1 # the first run downloads the CommonMark corpus- The CommonMark ratchet works per case.
core/tests/spec-baseline.jsonlists the 40 examples known to fail, and any other example that fails breaks the build. The corpus is pinned by SHA-256, so the denominator can't change silently. - Development happens on my self-hosted Gitea, where Woodpecker runs the pipelines in
.woodpecker/: the gate on a pinnedfedora:44image, a gcc/clang matrix, and a MinGW cross-build of the Windows binary. Pushing a version tag builds the Linux and Windows release archives. - This GitHub repository is a one-way mirror of that one, so Woodpecker does not run here.
.github/workflows/check.ymlruns the samemake checkin the same image; that is the badge above. Changes land on Gitea, so a pull request opened here cannot be merged directly, and the pull requests themselves live there too — theReviewed-onlinks in merge commits won't resolve for you. - Not covered by the gate: native MSVC, macOS, and actual printing.
core/ parser (flat + tree), HTML renderer; C standard library only
apps/printer/ md-printer: entry point + Win32/GDI, Cocoa, GTK/Cairo backends
apps/reader/ md-reader: terminal layout (no curses dependency) + ncurses UI
tools/ spec runner, pathological-input guard, doc-link checker
scripts/ check.sh (the gate), open-pr.sh
docs/ architecture, decisions (ADRs), support matrix, roadmap
.woodpecker/ CI pipelines for Gitea; .github/ runs the same gate here
AGENTS.md the instructions the agents work under
GOVERNANCE.md who may approve, merge and release
Apache-2.0. See LICENSE and NOTICE. © 2026 Duval Analytics LLC, my company.