@gmb/bitmark-parser

@gmb/bitmark-parser

A high-performance parser for bitmark, powered by WebAssembly. Provides both a programmatic API and a CLI for converting between bitmark markup and JSON.

Installation

npm install @gmb/bitmark-parser

Programmatic API (Node.js)

import { convert, parse, lex, breakscapeText, unbreakscapeText, info, version } from "@gmb/bitmark-parser";

// Convert bitmark to JSON (auto-detects input format)
const json = convert("[.article]\nHello **bold**");
console.log(json);

// Convert JSON back to bitmark
const bitmark = convert('[{"bitmark":"[.article]\\nHello **bold**","bit":{"type":"article","body":"Hello **bold**"}}]');
console.log(bitmark);

// Parse bitmark to JSON (same as convert for bitmark input)
const parsed = parse("[.article]\nHello **bold**");

// Lex bitmark to token dump
const tokens = lex("[.article]\nHello **bold**");

// Lex with a specific stage
const bitmarkTokens = lex(input, "lex-bitmark");
const textTokens = lex(input, "lex-text");

// Breakscape / unbreakscape text
const escaped = breakscapeText("[!example]", "bitmark++", "body");
const unescaped = unbreakscapeText(escaped, "bitmark++", "body");

// Query supported bit types
const bitInfo = info("list", "text");

// Get library version
console.log(version());

API

convert(input: string, optionsJson?: string): string

Auto-detect input format and convert between bitmark and JSON.

Options (passed as a JSON string):

• mode — "optimized" (default) or "full"
• warnings — include validation warnings (default: false)
• plainText — output text as plain text (default: false)
• pretty — prettify JSON output (default: false)
• indent — indent size for pretty JSON (default: 2)

parse(input: string): string

Parse bitmark text and return the AST as a JSON string.

lex(input: string, stage?: string): string

Lex bitmark text and return one token per line.

Stages:

• "lex" — Combined two-level lexer (default)
• "lex-bitmark" — Bitmark structural tokens only
• "lex-text" — Text formatting tokens only

breakscapeText(input: string, format?: string, location?: string): string

Breakscape text (escape bitmark special characters).

• format — "bitmark++" (default) or "plainText"
• location — "body" (default) or "tag"

unbreakscapeText(input: string, format?: string, location?: string): string

Unbreakscape text (unescape bitmark special characters).

• format — "bitmark++" (default) or "plainText"
• location — "body" (default) or "tag"

info(infoType?: string, format?: string, bit?: string, pretty?: boolean, indent?: number): string

Query information about supported bit types.

• infoType — "list" (default), "bit", "all", or "deprecated"
• format — "text" (default) or "json"
• bit — filter to a specific bit type (when infoType is "bit")
• pretty — prettify JSON output (default: false)
• indent — indent size for pretty JSON (default: 2)

version(): string

Return the library version string.

generate(json: string): string

Generate bitmark text from JSON. Not yet implemented — throws an error.

CLI

The CLI binary is bitmark-parser-wasm.

# Convert bitmark to JSON (auto-detects format)
bitmark-parser-wasm convert input.bitmark
bitmark-parser-wasm convert input.bitmark -o output.json

# Convert JSON to bitmark
bitmark-parser-wasm convert input.json -o output.bitmark

# Convert with options
bitmark-parser-wasm convert input.bitmark --mode full --pretty --warnings

# Parse a bitmark file to JSON
bitmark-parser-wasm parse input.bitmark
bitmark-parser-wasm parse input.bitmark -o output.json
bitmark-parser-wasm parse input.bitmark --mode full

# Lex instead of parse
bitmark-parser-wasm parse --stage=lex input.bitmark

# Available stages: all (default), lex, lex-bitmark, lex-text
bitmark-parser-wasm parse --stage=lex-bitmark input.bitmark

# Breakscape / unbreakscape text
bitmark-parser-wasm breakscape input.txt
bitmark-parser-wasm breakscape input.txt --format plainText --location tag
bitmark-parser-wasm unbreakscape input.txt

# Query bit type information
bitmark-parser-wasm info
bitmark-parser-wasm info all -f json --pretty
bitmark-parser-wasm info bit --bit article

# Generate bitmark from JSON (not yet implemented)
bitmark-parser-wasm generate input.json output.bitmark

All commands support -o, --output <file> and -a, --append flags. Commands that accept input support file paths, literal strings, or stdin (when no arguments are given).

Browser Usage

The package includes pre-built browser bundles with the WASM module.

CDN (jsdelivr / unpkg)

<script type="module">
  import init, { parse } from "https://cdn.jsdelivr.net/npm/@gmb/bitmark-parser@latest/dist/browser/bitmark-parser.min.js";

  await init();

  const json = parse("[.article]\nHello **bold**");
  console.log(json);
</script>

Bundler (webpack / vite)

import init, { parse, lex } from "@gmb/bitmark-parser/browser";

await init();
const json = parse("[.article]\nHello");

License

ISC — © 2023–2026 Get More Brain Ltd.