Skip to content
HeftyBPublic

About

Native C Markdown toolkit: CommonMark parser (93.9% of spec), OS-native print CLI, terminal reader. AI-assisted.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

mdtools

check

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.

Why this exists, and how it was built

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 check itself 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.

Status

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

What it does not do (yet)

  • 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.c exists to measure spec compliance. Like the spec, it passes raw HTML and javascript: 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.

Build and run

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 dialog

macOS: 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.

Verification: make check

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.json lists 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 pinned fedora:44 image, 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.yml runs the same make check in 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 — the Reviewed-on links in merge commits won't resolve for you.
  • Not covered by the gate: native MSVC, macOS, and actual printing.

Layout

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

License

Apache-2.0. See LICENSE and NOTICE. © 2026 Duval Analytics LLC, my company.

About

Native C Markdown toolkit: CommonMark parser (93.9% of spec), OS-native print CLI, terminal reader. AI-assisted.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages