markz

markz is a small, opinionated Markdown, and the one package that reads it, with no dependencies. It has one fixed dialect, a compact tree that maps every node back to the source, HTML output, and no options.

import { html, parse } from "@amitkaps/markz";

const page = html(markdown);

const doc = parse(markdown); // a read-only, source-mapped tree
console.log(doc.warnings); // what it didn't read, and what to write instead

The whole API is seven functions (parse, html, walk, textContent, ids, headings and position), the read-only Document and the frozen list of warning codes, in Reference. None of them takes options.

Install

pnpm add @amitkaps/markz

Each release's package is also attached to its GitHub release. In Node, markz needs 26 or newer, the Node it's built and tested on. In the browser, it needs the browsers craftz names: Chrome and Edge from the last 12 months, Firefox's oldest supported ESR, and Safari from the last three majors. It is one ES module with no dependencies and no Node APIs, so the same file runs in Node, browsers and workers.

A page with no build step imports it from a CDN, which serves it minified:

<script type="module">
  import { html } from "https://cdn.jsdelivr.net/npm/@amitkaps/[email protected]/+esm";
</script>

The language

markz reads the Markdown people already write: # headings, _emphasis_, **strong**, - lists, fenced code, links, images, tables, tasks and ~~strikethrough~~. On top of that:

To write	Write
Metadata	key: value lines between --- lines, at the very top
A class, id or attribute	{.class #id key=value open} above a block, or after a link
A styled word	[text]{.class}
An inline element	[Ctrl]{@kbd}
A block element	{@details} … {/details}, or [label]{@name /}
Math	$x$ in a line, or a $$ block
A value from code	${name}, kept whole for the page to evaluate
HTML	a ```=html fence
A comment	<!-- … --> on lines of its own

There is one way to write each thing. Forms that make a parser read ahead and change its mind, such as setext headings, reference links, raw HTML in text and indented code, aren't part of the language. They stay literal text and add a warning naming the form to write instead. markz never guesses what a document meant. Syntax has the whole language at a glance, and Grammar states it exactly.

Principles

• One package: parser, tree utilities and HTML, with no dependencies.
• Small: at most 20 KB gzip, enforced on every change.
• No configuration. The language is fixed, so every project reads a document the same way.
• Linear time. One pass, no backtracking, whatever the input.
• A flat, read-only tree with exact source offsets on every node. Transformations are folds that build something new.
• Safe HTML by construction. Outside ```=html blocks, nothing a document says can put script on the page.
• No footguns. Every input does what it looks like, or gets a warning that says what to write. Rejected syntax is never reinterpreted, and prose that only looks like syntax stays prose.
• Other tools may differ, but must not damage. GitHub may show an element as text, but it hides nothing, and links to headings work there too. markz reads what formatters write, so formatting never changes what a document means.

Not a drop-in Markdown parser

markz reads its language, not every Markdown in the wild. Pasted or generated Markdown often uses forms it leaves out, like reference links, bare URLs, raw HTML, footnotes and named entities. Converting a document means fixing what doc.warnings lists.

Read more

• Usage: render, check a document, read its metadata, build a contents list, and what to tell your agents.
• Syntax: every construct, what it's limited to, and what's left out.
• Reference: every export, and the tree it works on.
• Grammar: the language in EBNF, with the side rules that settle each choice.
• Design: the tree, source offsets, the parser, HTML and security.
• Quality: how markz is tested, and how to read the report of conformance, size and speed on each commit.
• Lessons: what building it taught.
• Development: build, test, release and deploy the site.

markz builds on CommonMark and GFM, takes its cuts and attribute syntax from djot and its math from pandoc and GitHub, and uses micromark as the oracle its tests check against.