yamd

YAMD - Yet Another Markdown Document (flavour)

Simplified version of CommonMark.

For formatting check YAMD struct documentation.

Quick start

use yamd::deserialize;

let input = "# Hello\n\nA paragraph with **bold** text.";
let yamd = deserialize(input);

// Access the AST
assert_eq!(yamd.body.len(), 2);

// Round-trip back to markdown
assert_eq!(yamd.to_string(), input);

Two APIs

• deserialize returns a nested Yamd document — a tree of typed nodes, suitable for walking, pattern-matching, or round-tripping back to markdown via Display. The AST makes invalid nestings unrepresentable, and deserialize is fuzz-tested for panic-freedom and property-tested for round-trip fidelity.
• parse returns a flat Vec<Op> of Start/End/Value events, where Content borrows from the source when possible. Reach for it when you want streaming rendering or zero-copy text processing without materializing the full tree. to_yamd promotes an event stream to the tree form. Fuzz-tested for panic-freedom (transitively, via deserialize); the AST's type-level invariants and round-trip property do not apply at this layer.

Reasoning

YAMD exchanges CommonMark's context-dependent rules for a uniform set: every node is treated the same, and escaping is resolved at the lexer. The goal is a parser that's easier to reason about locally, with fewer special cases to remember.

Rendering is out of scope; Yamd is an AST you walk and render however you like. With the serde feature enabled, the AST is also serde-serializable.

Difference from CommonMark

YAMD reuses most of CommonMark's syntax but diverges in a few places.

Escaping

Escaping is handled at the [lexer] level: any character following \ is treated as a literal.

Example:

Precedence

CommonMark distinguishes container blocks from leaf blocks and gives container-block markers higher precedence. YAMD does not distinguish block types — every node is treated the same, so there are no precedence rules to remember.

Example:

To get two separate ListItems, escape the backticks:

The reasoning: issues like this should be caught by tooling such as linters or language servers — that tooling doesn't exist yet.

Nodes

See [nodes] for the full list of supported nodes and their formatting. Start with YAMD.

MSRV

YAMD minimal supported Rust version is 1.87.