Case Study

How Carve was designed: the landscape it grew out of, the principles that guided it, the syntax it ended up with, and the parsing / implementation considerations that fall out of those choices.

The full case study was split into themed chapters so each one stands on its own.

Chapters

• Background — the landscape of lightweight markup, what each existing format teaches us, and what observation of non-technical users reveals.
• Design — Carve's core principles, anti-patterns to avoid, and a reflection on why we don't just patch Markdown.
• Syntax Specification — the spec proper. Every construct, every delimiter, every rule.
• Parsing & AST — block-then-inline parsing strategy and the shape of the AST it produces.
• Compatibility, Comparison & Open Questions — migration paths from other formats, feature-by-feature comparison matrix, and what's still being debated.
• Implementation & Reflection — practical concerns for implementers, and what success looks like.
• Appendices — quick reference card, full example document, influences and acknowledgments.

Related

• Examples — side-by-side Carve source and the HTML it produces.
• Formal grammar — EBNF specification.
• Reference implementation — @markup-carve/carve on TypeScript.