The parser

View as Markdown Open in Claude ↗

The bitmark parser is the reference implementation of bitmark. It is offered by Get More Brain for the community, as open source under the ISC licence. These docs describe what it does; when the two disagree, the parser is right.

One core, every platform

The parser is one Rust core compiled to WebAssembly. It runs in the browser, in Node.js, as a command-line tool (ready-made for macOS, Linux and Windows) and directly in Rust. Every one of them gives the same result.

What it does

  • Converts bitmark to JSON and JSONL, and back.
  • Writes HTML and XML, and imports standards documents in NISO STS XML.
  • Checks content against the language definitions and reports errors, warnings and notes, each with a stable code.
  • Compares two documents as a semantic diff: tag order, spacing and omitted defaults are not differences.
  • Records where each bit sits in the input and in the output (--bit-spans, --bit-anchors), so tools can cite and link back.
  • Reports what a conversion could not carry over (--mapping-report) instead of losing it silently.

Get it

  • npm: npm install @gmb/bitmark-parser for Node.js and bundlers; the package also brings the bitmark command.
  • Without installing: npx @gmb/bitmark-parser convert file.bitmark.
  • In a web page: load it from a CDN such as jsDelivr (https://cdn.jsdelivr.net/npm/@gmb/bitmark-parser@latest/dist/browser/bitmark-parser.min.js); pin a version instead of latest in production.
  • VS Code: the bitmark language extension adds highlighting, problems, completion, hover and live previews (not on the Marketplace yet).
  • Try it first: the bitmark playground.

Quick start

bash
npx @gmb/bitmark-parser convert first.bitmark --output-format jsonl
npx @gmb/bitmark-parser convert first.json --input-format json --output-format bitmark
npx @gmb/bitmark-parser diff old.bitmark new.bitmark
js
import { convert } from "@gmb/bitmark-parser";

const json = convert("[.article]\nHello", { inputFormat: "bitmark", warnings: true });
const bitmark = convert(json, { inputFormat: "json", outputFormat: "bitmark" });

In the browser, call await init() once before the first convert. Getting started walks through a first bit.

JSONL for APIs

JSONL, one bit per line, is the recommended format for delivering bitmark through an API. Each line stands alone, so a reader can stream a large document, stop early or fetch part of it. The parser reads JSONL back as easily as it writes it:

bash
npx @gmb/bitmark-parser convert book.bitmark --output-format jsonl -o book.jsonl
npx @gmb/bitmark-parser convert book.jsonl --output-format bitmark

Versions

Two numbers matter. The parser has its own release number (for example 7.21.2); the language it implements is bitmark 3. Every JSON entry names both in its parser field. These docs are built from a parser release, so they always describe what that release does.

Under the hood

A readable grammar describes the language and is checked against the parser in every build, so the two cannot drift apart. Editors highlight bitmark through the parser's own semantic tokens, so what is coloured is exactly what the parser reads.