@orkestrel/markdown

A types-first markdown layer over @orkestrel/html: a linear-time scanner that parses GitHub-Flavored Markdown into a typed AST, a stateful Markdown workspace that queries, rewrites, folds, and streams that AST, and standalone projections that carry it out to sanitized HTML or canonical markdown source and carry an HTML AST back in.

Parse a document with the createMarkdown function, query and rewrite the AST the handle holds, then write it back out with the renderHTML or renderMarkdown function. Where the source is HTML instead, the htmlToMarkdown function brings it the other way. Part of the @orkestrel line.

• One AST, several projections. Nodes are plain readonly data keyed by element; parsing, querying, rewriting, folding, streaming, and every conversion are operations over it.
• Each direction lives here. markdownToHTML and htmlToMarkdown are inverse projections across the boundary, because what an HTML subtree means in markdown is markdown's knowledge, not html's.
• Sanitized by default, with no opt-out. renderHTML takes one argument and composes @orkestrel/html's sanitize floor, so there is no call shape that emits unsafe HTML.
• Bounded by design. Every parse, traversal, and projection is iterative and depth-capped, so malformed or hostile input degrades to literal text instead of throwing.

Install

npm install @orkestrel/markdown

Requirements

• Node.js >= 22.12
• Ships ES and CommonJS builds with its own .d.ts types
• Depends at runtime on @orkestrel/html and @orkestrel/contract

Usage

import { createMarkdown, htmlToMarkdown, renderHTML, renderMarkdown } from '@orkestrel/markdown'
import { parseDocument as parseHTML } from '@orkestrel/html'

const markdown = createMarkdown('# Hi\n\nRead the [guide](./guide.md) for more, *thanks*.')

markdown.document
// { element: 'document', children: [...] } — the typed, render-agnostic AST

renderHTML(markdown.document)
// '<h1>Hi</h1><p>Read the <a href="./guide.md">guide</a> for more, <em>thanks</em>.</p>'

// …and back the other way.
renderMarkdown(htmlToMarkdown(parseHTML('<h1>Release notes</h1><p>Ship <b>fast</b>.</p>')))
// '# Release notes\n\nShip **fast**.'

createMarkdown (or new Markdown) runs a two-phase parse — block phase, then inline phase — and holds the result as a stateful workspace exposing find / filter / map / reduce / fold / stream / iteration over the AST. renderHTML projects that AST onto html's AST, sanitizes it against a floor no option can lower, and serializes it. renderMarkdown writes canonical markdown source instead. htmlToMarkdown folds an HTML AST back down to a MarkdownDocument, re-sanitizing every destination as it goes. Guards (isMarkdownNode, isMarkdownDocument, isBlockNode, isInlineNode) validate an AST that arrives from outside — an RPC payload, a cached document — without ever throwing, and the non-recursive leaf nodes each compile to a @orkestrel/contract bundle of guard, parser, JSON Schema, and seeded generator.

Laws

• Markdown fixpoint — parseDocument(renderMarkdown(document)) deep-equals a parser-produced document, and renderMarkdown is idempotent.
• Projection anchor — parseDocument(renderMarkdown(htmlToMarkdown(x))) deep-equals htmlToMarkdown(x): whatever the projection emits, markdown can write it and read it back unchanged.

Each round-trip law holds within the depth budget — markdown's MAX_DEPTH, plus html's own cap on the inbound trip; beyond it only totality is promised.

• Sanitized output — renderHTML refuses javascript:, data:, vbscript:, file:, and protocol-relative destinations, removes unsafe subtrees whole, and strips every handler and styling attribute, whatever the input AST claims.

HTML is richer than markdown, so what survives the inbound trip is the projected AST, not the input bytes: comments and doctypes vanish, an element with no markdown meaning unwraps to its children, and block content inside a table cell flattens to one line.

Guide

For the full surface — the AST shape, the two-phase parse, the sanitization policy, the projection seam, and the contract-backed leaf shapes — see guides/markdown.md.

Package

Published as a single typed entry point per the exports field in package.json.

License

MIT © Orkestrel — see LICENSE.