Getting started

View as Markdown Open in Claude ↗

Three steps take you from a first bit to JSONL: try it in the playground, convert it on the command line, then use the parser in your own code.

1. Try it in the playground

The bitmark playground shows bitmark and its JSON side by side, with nothing to install. Paste this bit:

bitmarkOpen in playground ↗
[.article]
[@id: first-bit ]
bitmark represents content as (+bold)typed, addressable bits(-bold).

[.article] is the bit's type, [@id: first-bit ] its permanent ID, and (+bold)…(-bold) marks the words as bold.

2. Convert it on the command line

Save the bit as first.bitmark and convert it with the parser's command-line tool, which npx downloads for you:

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

The result is one line of JSON per bit:

json
{"bit":{"type":"article","format":"bitmark++","bitLevel":1,"id":["first-bit"],"body":[{"type":"paragraph","content":[{"text":"bitmark represents content as ","type":"text"},{"text":"typed, addressable bits","type":"text","marks":[{"type":"bold"}]},{"text":".","type":"text"}]}]},"parser":{"version":"7.21.2","bitmarkVersion":"3"},"bitmark":"[.article]\n[@id: first-bit ]\nbitmark represents content as (+bold)typed, addressable bits(-bold)."}

Each line holds the bit, the parser's version and the source it came from. Leave out --output-format to get a JSON array instead; --pretty indents it.

3. Use it in your code

Install the parser and call convert:

bash
npm install @gmb/bitmark-parser
js
import { convert } from "@gmb/bitmark-parser";

const source = "[.article]\n[@id: first-bit ]\nbitmark represents content as (+bold)typed, addressable bits(-bold).";
const jsonl = convert(source, { inputFormat: "bitmark", outputFormat: "jsonl" });

// With warnings on, each entry's `parser` field lists what needs fixing.
const entries = JSON.parse(convert(source, { inputFormat: "bitmark", warnings: true }));
console.log(entries[0].parser.warnings ?? "no warnings");

The same call works in the browser and in Rust; see The parser.

Next

  • The basics: bits, tags and chains.
  • Text formatting: styling text with toggle tags.
  • The reference lists every bit type, tag, card and resource.