The Markdown engine

Decision

Use remark/unified to parse Markdown into mdast, then transform it into a BEMJSON tree. This is the implemented pipeline in 1.0.0.

Context

nuckty needs structural Markdown output for its template engine, plus extension points for directives and content transformations. A Markdown-to-HTML string alone does not provide that structure.

Alternatives

A token-stream parser. A bridge can reconstruct nesting from tokens, but must keep track of paired opening and closing tokens and their context.

An HTML-producing compiler. This provides ready markup, but structural nu templates would require another representation or an HTML parser.

A typed syntax tree. mdast represents nested Markdown nodes directly. The bridge can map headings, lists, links, and images by node type.

remark-parse builds mdast; remark-gfm and remark-directive add the syntax nuckty supports. unified composes parsing and transformations. The bridge then produces nodes for the same nu renderer that processes document blocks.

Markdown extensions can register a remark plugin or a directive handler. Content-specific features such as videos, galleries, and Russian typography remain separate packages.

The choice is based on the structure and extension contract. This documentation does not claim a speed advantage without a reproducible benchmark of the complete build.

Consequences

The Markdown bridge and its transformations use mdast. Extension authors receive mdast children, not HTML or BEMJSON children, in directive handlers.

Russian typography is optional. An English-language site can omit that extension. For supported syntax and link-resolution behavior, see the Markdown guide.