ChoirMark

An open format for documents — content carries the meaning, themes carry the look. Like CommonMark, but for whole documents.

ChoirMark is CommonMark plus a small, closed extension profile that assigns roles to content (:::role blocks, {#id} attributes, [@…] references) per document class — letter, folio, deck, ledger, brief. A .cmk file describes what each part of a document is; a theme decides how it looks, and an engine decides what it computes. ChoirMark owns exactly one deterministic transform: a resolved .cmk → a canonical, role-tagged HTML pivot.

---
class: letter
---

:::sender-block
Acme Corporation
:::

::date[March 3, 2026]

Dear Ms. Rivera,

Thank you for your continued business.

:::closing
Sincerely,
:::

See spec/spec.md for the normative format and spec/GUIDE.md for the authoring guide (why it exists, how to choose a class, how to represent common content). The spec is also the conformance suite: every example block in it becomes a test.

Install

npm install choirmark

Requires Node ≥ 20.

Usage

import { parse, toHtml, vocabularies } from 'choirmark'

const html = toHtml(source)   // .cmk source → role-tagged HTML pivot
const tree = parse(source)    // .cmk source → the mdast document model
vocabularies.letter           // the frozen role vocabulary for a class

toHtml is synchronous and renders the pivot only — themes, layout, pagination, and PDF are an engine's job, downstream of the border. Raw HTML in the source is escaped, never passed through.

License

The reference implementation is MIT (see LICENSE); the specification is CC BY-SA 4.0 (see spec/LICENSE).

choirmark.org