markplus_core

A universal, high-performance Markdown → AST compiler written in Rust.

markplus_core parses Markdown (with optional YAML frontmatter) into a structured, versioned JSON AST. It does not render HTML or Typst — rendering is the responsibility of a downstream crate or plugin that consumes the AST. This keeps the parser lean and completely independent of any output target.

Key capabilities

Project structure

markplus_core/
├── Cargo.toml
├── docs/
│   ├── usage.md          ← API / CLI usage guide
│   └── ast-reference.md  ← Markdown → AST node reference
└── src/
    ├── lib.rs            ← Public API (native + Wasm exports)
    ├── main.rs           ← mpc CLI (single-command AST emitter)
    ├── config.rs         ← Parser options / FrontmatterMode
    ├── event_filter.rs   ← Frontmatter stripper, passes events through
    ├── ast.rs            ← Stack-based AST builder
    └── json.rs           ← SiteAsset wire format

Quick start

Build

cargo build --release        # native lib + mpc CLI
wasm-pack build --target web # WebAssembly package → pkg/

CLI

# Emit compact AST JSON
mpc note.md

# Emit pretty-printed AST JSON
mpc --pretty note.md

Rust library

use markplus_core::{parse_document, parse_body};

// Full document with frontmatter
let asset = parse_document(raw_md)?;
let json  = asset.to_json()?;      // write to note.json

// Pre-stripped body only
let ast = parse_body(body_str);

WebAssembly (JavaScript)

import init, { parse_to_ast, parse_document_to_json } from './pkg/markplus_core.js';
await init();

// Plain markdown body → AST array JSON string
const ast = JSON.parse(parse_to_ast(markdownBody));

// Raw markdown (frontmatter ignored in wasm) → full SiteAsset JSON string
const site = JSON.parse(parse_document_to_json(rawMarkdown));

Wire format — note.json

{
  "schema": 1,
  "meta": {
    "title": "RFSoC Mixer Design Notes",
    "tags": ["rfsoc", "dsp"],
    "date": "2026-05-30"
  },
  "ast": [
    { "t": "heading", "level": 1, "children": [{ "t": "text", "text": "High Frequency Core" }] },
    { "t": "fenced",  "name": "simby", "attrs": {}, "raw": "[RFSoC] ──► [Filter]" }
  ]
}

See docs/ast-reference.md for the full AST node schema.

Schema

The file schema/markplus-ast.v1.schema.json is a JSON Schema 2020-12 document that formally defines every node type in the AST.

It is the source of truth for both markplus_core (producer) and all downstream renderers and plugins (consumers). When a new node type is added, the schema is updated first — then the core, then the renderers.

Validate your AST

# Python (jsonschema)
pip install jsonschema
mpc note.md | python -c "
import sys, json
from jsonschema import validate
ast = json.loads(sys.stdin.read())
schema = json.load(open('schema/markplus-ast.v1.schema.json'))
validate(instance=ast, schema=schema)
print('valid')
"

See schema/CHANGELOG.md for the schema versioning policy.

Further reading

• docs/usage.md — detailed API and CLI usage
• docs/ast-reference.md — every Markdown construct mapped to its AST node
• schema/markplus-ast.v1.schema.json — formal JSON Schema (machine-readable)
• schema/CHANGELOG.md — schema versioning history and breaking-change policy