@geml/geml 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GEML contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @geml/geml
+
+Reference parser, validator, renderer, and CLI for **GEML** — the General
+Expressive Markup Language: a plain-text document format that stays legible to
+people and reliable for machines. Every kind of structured content — code,
+tables, diagrams, math, callouts, metadata — is carried on **one** primitive,
+the typed block:
+
+```
+=== code {#hello lang=python}
+print("hi")
+===
+```
+
+References are checked at build time (a dangling `#id` is an error, not a silent
+dead link), and the parser emits a document-model JSON with `diagnostics`, so
+agents and CI get a structured pass/fail signal.
+
+## Install
+
+```sh
+npm install -g @geml/geml   # global CLI — installs the `geml` command
+# or, per project:
+npm install @geml/geml      # library + local bin
+```
+
+Requires Node ≥ 18.
+
+## CLI
+
+Every command reads a file path, or `-` for stdin. Exit codes: `0` ok ·
+`1` document/operation error · `2` usage error.
+
+```sh
+geml check  file.geml            # validate only: diagnostics + exit code
+geml check --json file.geml      # machine-readable: diagnostics array (or {"error":…} on IO failure)
+geml        file.geml            # full document-model JSON
+geml render file.geml -o out.html  # one self-contained, interactive HTML file
+geml export file.geml -o out.md    # project to GitHub-Flavored Markdown (lossy; notes on stderr)
+geml convert in.md     -o out.geml # Markdown -> GEML
+geml fmt    file.geml            # canonical re-format (idempotent)
+geml history <commit|verify|show|restore> file.geml [...]   # .gemlhistory sidecar
+geml --help | --version          # --version --json prints {"parser","spec"}
+```
+
+The agent loop: write `.geml` → `geml check` → fix on non-zero → done.
+
+## Library
+
+```js
+import { parse, serialize, renderHtml, gemlToMd, mdToGeml } from "@geml/geml";
+
+const doc = parse(src);                 // { kind:"document", children, ids, diagnostics }
+const ok  = !doc.diagnostics.some(d => d.severity === "error");
+const html = renderHtml(doc);           // one self-contained HTML string
+const md   = gemlToMd(doc).md;          // GitHub-Flavored Markdown (lossy)
+const geml = mdToGeml(markdown).geml;   // the inverse
+const canonical = serialize(doc);       // GEML text; parse(serialize(parse(x))) is stable
+```
+
+`parse(src, { resolveDoc })` enables cross-document reference checking — pass a
+function that returns another file's source by path (or `null`).
+
+## Documentation
+
+Full normative spec, history-sidecar spec, and format comparison live in the
+[repository](https://github.com/xiongjy2104/geml-spec). The spec is itself
+written in GEML (`GEML-spec.geml`) and parsed clean on every test run.
+
+## License
+
+MIT.

package/dist/attrs.d.ts

@@ -0,0 +1,9 @@
+export type Value = string | number | boolean;
+export interface Attrs {
+    id?: string;
+    classes: string[];
+    attrs: Record<string, Value>;
+}
+export declare function coerce(raw: string): Value;
+export declare function tokenize(s: string): string[];
+export declare function parseAttrs(src: string): Attrs;

package/dist/attrs.js

@@ -0,0 +1,64 @@
+// Shared attribute-object and value typing (§4), used by the block scanner
+// and the inline parser.
+// §4 value typing: quoted -> string, true/false -> boolean, integer/float
+// syntax -> number, any other bare word -> string. No arrays/dates/tables.
+export function coerce(raw) {
+    const t = raw.trim();
+    if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) {
+        return t.slice(1, -1); // quoted -> always string
+    }
+    if (t === "true")
+        return true;
+    if (t === "false")
+        return false;
+    if (/^[+-]?\d+$/.test(t))
+        return parseInt(t, 10);
+    if (/^[+-]?(\d+\.\d*|\.\d+|\d+)([eE][+-]?\d+)?$/.test(t) && /[.eE]/.test(t))
+        return parseFloat(t);
+    return t; // bare word -> string
+}
+// Split on whitespace while keeping double-quoted spans intact.
+export function tokenize(s) {
+    const out = [];
+    let cur = "";
+    let inQuote = false;
+    for (const ch of s) {
+        if (ch === '"') {
+            inQuote = !inQuote;
+            cur += ch;
+        }
+        else if (!inQuote && /\s/.test(ch)) {
+            if (cur) {
+                out.push(cur);
+                cur = "";
+            }
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+}
+// Parse `{#id .class key=val key2="a b"}` (braces included).
+export function parseAttrs(src) {
+    const inner = src.trim().replace(/^\{/, "").replace(/\}$/, "");
+    const out = { classes: [], attrs: {} };
+    for (const tok of tokenize(inner)) {
+        if (tok.startsWith("#")) {
+            out.id = tok.slice(1);
+        }
+        else if (tok.startsWith(".")) {
+            out.classes.push(tok.slice(1));
+        }
+        else {
+            const eq = tok.indexOf("=");
+            if (eq > 0)
+                out.attrs[tok.slice(0, eq)] = coerce(tok.slice(eq + 1));
+            else
+                out.attrs[tok] = true; // bare word -> boolean flag (e.g. `hidden`)
+        }
+    }
+    return out;
+}

package/dist/chart.d.ts

@@ -0,0 +1,28 @@
+import { type Value } from "./attrs.js";
+import { type TableModel } from "./table.js";
+export type ChartType = "bar" | "line" | "area" | "pie" | "scatter";
+export type RowScope = "data" | "all" | "summary";
+export interface ChartDataset {
+    categories: string[];
+    numbers: Record<string, number[]>;
+    seriesOf?: string[];
+}
+export interface ChartModel {
+    type: ChartType;
+    x: string;
+    y: string[];
+    series?: string;
+    size?: string;
+    rows: RowScope;
+    dataRef: string;
+    dataset: ChartDataset;
+}
+export interface ChartDiag {
+    severity: "error" | "warning";
+    message: string;
+}
+export interface ChartResult {
+    model: ChartModel | null;
+    diagnostics: ChartDiag[];
+}
+export declare function buildChart(attrs: Record<string, Value>, table: TableModel): ChartResult;

package/dist/chart.js

@@ -0,0 +1,128 @@
+// GEML reference parser — chart-from-table (§7 geml-chart renderer).
+//
+// A `diagram {format=geml-chart data=#id ...}` binds to a table and is drawn
+// from a closed set of encoding channels (x, y, series, size). `type` only
+// changes how those channels are drawn; it never adds new attributes. The
+// processor validates the attributes against the referenced table's model and
+// normalizes the selected rows into a dataset for a renderer. See the design
+// doc and §7.
+const TYPES = new Set(["bar", "line", "area", "pie", "scatter"]);
+// Channels each type can use; supplying any other is a warning (ignored).
+const USES = {
+    bar: new Set(["x", "y", "series"]),
+    line: new Set(["x", "y", "series"]),
+    area: new Set(["x", "y", "series"]),
+    scatter: new Set(["x", "y", "series", "size"]),
+    pie: new Set(["x", "y"]),
+};
+function str(v) {
+    return v === undefined ? undefined : typeof v === "string" ? v : String(v);
+}
+export function buildChart(attrs, table) {
+    const diagnostics = [];
+    const err = (m) => diagnostics.push({ severity: "error", message: m });
+    const warn = (m) => diagnostics.push({ severity: "warning", message: m });
+    const fail = () => ({ model: null, diagnostics });
+    const typeRaw = str(attrs["type"]);
+    if (!typeRaw) {
+        err("chart: missing `type`");
+        return fail();
+    }
+    if (!TYPES.has(typeRaw)) {
+        err(`chart: unknown type \`${typeRaw}\` (supported: bar, line, area, pie, scatter; use format=vega-lite for others)`);
+        return fail();
+    }
+    const type = typeRaw;
+    // Validate rows scope up front so a bad value is reported even when a column
+    // name is also wrong.
+    const rowsAttr = (str(attrs["rows"]) ?? "data");
+    if (!["data", "all", "summary"].includes(rowsAttr)) {
+        err(`chart: unknown rows scope \`${rowsAttr}\` (data|all|summary)`);
+        return fail();
+    }
+    const x = str(attrs["x"]);
+    const yRaw = str(attrs["y"]);
+    if (!x)
+        err("chart: missing required channel `x`");
+    if (!yRaw)
+        err("chart: missing required channel `y`");
+    if (!x || !yRaw)
+        return fail();
+    let y = yRaw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+    if (y.length === 0) {
+        err("chart: `y` lists no columns");
+        return fail();
+    }
+    // Wrong-channel warnings (channel present but unused by this type).
+    if (attrs["size"] !== undefined && !USES[type].has("size"))
+        warn(`chart: \`size\` is ignored for type \`${type}\``);
+    if (attrs["series"] !== undefined && !USES[type].has("series"))
+        warn(`chart: \`series\` is ignored for type \`${type}\``);
+    if (type === "pie" && y.length > 1) {
+        warn("chart: pie uses a single `y`; extra columns ignored");
+        y = [y[0]];
+    }
+    // Optional channels, only when used by this type.
+    const series = USES[type].has("series") ? str(attrs["series"]) : undefined;
+    const size = USES[type].has("size") ? str(attrs["size"]) : undefined;
+    // Resolve columns by header name (x, y, and any used optional channels).
+    const idx = (name) => table.columns.indexOf(name);
+    for (const name of [x, ...y, ...(series ? [series] : []), ...(size ? [size] : [])]) {
+        if (idx(name) < 0)
+            err(`chart: column \`${name}\` not found in table`);
+    }
+    if (diagnostics.some((d) => d.severity === "error"))
+        return fail();
+    // Select rows per scope.
+    let picked;
+    if (rowsAttr === "summary") {
+        if (!table.summary) {
+            err("chart: rows=summary but the table has no summary row");
+            return fail();
+        }
+        picked = [table.summary];
+    }
+    else if (rowsAttr === "all") {
+        if (!table.summary)
+            warn("chart: rows=all but the table has no summary row; using data rows");
+        picked = table.summary ? [...table.rows, table.summary] : table.rows;
+    }
+    else {
+        picked = table.rows;
+    }
+    // Normalize: x text + numeric y/size columns; series text. A non-empty
+    // non-numeric value in a numeric column is always an error; a row with an
+    // empty numeric cell is skipped (no data point).
+    const numCols = [...y, ...(size ? [size] : [])];
+    const xi = idx(x);
+    const si = series ? idx(series) : -1;
+    const numIs = numCols.map(idx);
+    const categories = [];
+    const numbers = {};
+    const seriesOf = [];
+    for (const c of numCols)
+        numbers[c] = [];
+    for (const row of picked) {
+        const cells = numIs.map((i) => row[i]);
+        if (cells.some((cell) => (cell?.text ?? "") !== "" && typeof cell?.value !== "number")) {
+            err("chart: non-numeric value in a y column");
+            return fail();
+        }
+        if (cells.some((cell) => (cell?.text ?? "") === ""))
+            continue;
+        categories.push(row[xi]?.text ?? "");
+        numIs.forEach((i, j) => numbers[numCols[j]].push(row[i].value));
+        if (series)
+            seriesOf.push(row[si]?.text ?? "");
+    }
+    const dataRef = (str(attrs["data"]) ?? "").replace(/^#/, "");
+    const dataset = { categories, numbers };
+    if (series)
+        dataset.seriesOf = seriesOf;
+    const model = { type, x, y, rows: rowsAttr, dataRef, dataset };
+    if (series)
+        model.series = series;
+    if (size)
+        model.size = size;
+    return { model, diagnostics };
+}

package/dist/from-md.d.ts

@@ -0,0 +1,5 @@
+export interface ConvertResult {
+    geml: string;
+    notes: string[];
+}
+export declare function mdToGeml(source: string): ConvertResult;

package/dist/from-md.js

@@ -0,0 +1,242 @@
+// GEML reference parser — Markdown → GEML conversion.
+//
+// Markdown's inline syntax (emphasis/strong/strike, code, links, images,
+// footnotes) is already a subset of GEML's (§5), so inline text passes through
+// unchanged. The work is mapping block constructs onto GEML's single typed-block
+// primitive (§3):
+//
+//   YAML frontmatter      -> === meta            (data)
+//   ``` fenced code        -> === code {lang=…}   (raw)
+//   $$ … $$ math block     -> === math            (raw)
+//   > blockquote           -> === note            (flow)
+//   GFM pipe table         -> === table           (visual body, §6)
+//   setext heading         -> ATX heading (§1: GEML headings are ATX-only)
+//   thematic break (---/***) -> dropped           (§1: not part of GEML)
+//
+// Anything else (ATX headings, lists, paragraphs) is already valid GEML.
+// Pick a fence length longer than any run of `=` that appears alone on a body
+// line (leading indentation included), so the close fence stays unambiguous
+// (§3 equal-length close rule) and the body's own `=` fences nest safely.
+function fenceFor(body) {
+    let max = 2;
+    for (const l of body) {
+        const m = /^\s*(=+)\s*$/.exec(l);
+        if (m)
+            max = Math.max(max, m[1].length);
+    }
+    return "=".repeat(Math.max(3, max + 1));
+}
+// Emit a typed block, auto-assigning a stable `#type-N` id (so converted blocks
+// are referenceable) unless one was already supplied or the block is `meta`.
+function emitBlock(out, type, attrs, body, ids) {
+    if (ids && type !== "meta" && !attrs.includes("#")) {
+        const n = (ids[type] = (ids[type] ?? 0) + 1);
+        const idAttr = `#${type}-${n}`;
+        attrs = attrs ? attrs.replace(/^\{/, `{${idAttr} `) : `{${idAttr}}`;
+    }
+    const fence = fenceFor(body);
+    out.push(attrs ? `${fence} ${type} ${attrs}` : `${fence} ${type}`);
+    out.push(...body);
+    out.push(fence);
+}
+// Fenced-code info strings that denote a diagram DSL (§7) rather than code.
+const DIAGRAM_LANGS = new Set(["mermaid", "graphviz", "dot", "d2", "plantuml"]);
+// `key: value` (YAML-ish) -> `key=value`, quoting values that need it.
+function metaLine(line) {
+    const m = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
+    if (!m)
+        return null;
+    let v = m[2].trim();
+    if (v === "")
+        return `${m[1]}=""`;
+    // Strip existing YAML quotes; re-quote only when the bare value would be
+    // re-tokenized (contains whitespace or a quote).
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))
+        v = v.slice(1, -1);
+    const bareSafe = /^[^\s"]+$/.test(v);
+    return bareSafe ? `${m[1]}=${v}` : `${m[1]}="${v.replace(/"/g, '\\"')}"`;
+}
+// Rewrite Markdown autolinks `<https://…>` / `<mailto:…>` into GEML links
+// `[url](url)` (GEML has no autolink syntax). Inline code spans are left intact.
+function autolinks(s) {
+    return s
+        .split(/(`[^`]*`)/)
+        .map((seg, i) => i % 2 === 1
+        ? seg
+        : seg
+            .replace(/<((?:https?|ftp):\/\/[^>\s]+)>/g, "[$1]($1)")
+            .replace(/<mailto:([^>\s]+)>/g, "[$1](mailto:$1)"))
+        .join("");
+}
+// GitHub-style heading anchor: drop code backticks (keep content), lowercase,
+// strip punctuation except `-`/`_`, collapse whitespace to hyphens. Used to keep
+// converted headings' ids in sync with Markdown TOC links.
+function githubSlug(text) {
+    return text
+        .replace(/`/g, "")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}
+const FENCE = /^(\s*)(`{3,}|~{3,})(.*)$/;
+const SETEXT_UL = /^=+\s*$/;
+const SETEXT_DASH = /^-+\s*$/;
+const THEMATIC = /^\s*([-*_])(\s*\1){2,}\s*$/;
+const TABLE_SEP = /^\s*\|?\s*:?-{1,}:?\s*(\|\s*:?-{1,}:?\s*)*\|?\s*$/;
+export function mdToGeml(source) {
+    const lines = source.replace(/\r\n?/g, "\n").split("\n");
+    const out = [];
+    const notes = [];
+    const ids = {}; // per-type id counters for auto-ids
+    let i = 0;
+    // YAML frontmatter (must be the very first line).
+    if (lines[0] === "---") {
+        let j = 1;
+        const meta = [];
+        while (j < lines.length && lines[j] !== "---" && lines[j] !== "...") {
+            const ml = metaLine(lines[j]);
+            if (ml)
+                meta.push(ml);
+            else if (lines[j].trim() !== "")
+                notes.push(`frontmatter line not converted: ${lines[j]}`);
+            j++;
+        }
+        if (j < lines.length) { // closing marker found -> it was frontmatter
+            emitBlock(out, "meta", "", meta, ids);
+            out.push("");
+            i = j + 1;
+        }
+    }
+    while (i < lines.length) {
+        const line = lines[i];
+        // Fenced code block.
+        const f = FENCE.exec(line);
+        if (f) {
+            const marker = f[2];
+            const info = f[3].trim().split(/\s+/)[0] ?? "";
+            const body = [];
+            let j = i + 1;
+            for (; j < lines.length; j++) {
+                const raw = lines[j];
+                // CommonMark: a closing fence is indented at most 3 spaces, uses the same
+                // marker, and is at least as long as the opener. A more-indented run of
+                // the same character is content — this is what lets a document *show*
+                // nested ``` fences without ending the block early.
+                const indent = raw.length - raw.trimStart().length;
+                const c = raw.replace(/\s+$/, "").trimStart();
+                if (indent <= 3 && c.length >= marker.length && c[0] === marker[0] && /^[`~]+$/.test(c))
+                    break;
+                body.push(raw);
+            }
+            if (DIAGRAM_LANGS.has(info))
+                emitBlock(out, "diagram", `{format=${info}}`, body, ids);
+            else
+                emitBlock(out, "code", info ? `{lang=${info}}` : "", body, ids);
+            i = j < lines.length ? j + 1 : j;
+            continue;
+        }
+        // Display math $$ … $$.
+        if (line.trim() === "$$") {
+            const body = [];
+            let j = i + 1;
+            for (; j < lines.length && lines[j].trim() !== "$$"; j++)
+                body.push(lines[j]);
+            emitBlock(out, "math", "", body, ids);
+            i = j < lines.length ? j + 1 : j;
+            continue;
+        }
+        // Setext heading: a text line followed by `===` or `---` underline. Checked
+        // before the thematic-break drop so dash underlines aren't lost.
+        if (line.trim() !== "" && !THEMATIC.test(line) && i + 1 < lines.length) {
+            const nxt = lines[i + 1];
+            if (SETEXT_UL.test(nxt)) {
+                out.push(`# ${line.trim()}`);
+                i += 2;
+                continue;
+            }
+            if (SETEXT_DASH.test(nxt)) {
+                out.push(`## ${line.trim()}`);
+                i += 2;
+                continue;
+            }
+        }
+        // Thematic break (---, ***, ___) -> dropped (not a GEML construct). Any
+        // dash underline has already been consumed by the setext check above.
+        if (THEMATIC.test(line)) {
+            notes.push(`dropped thematic break at line ${i + 1}`);
+            i++;
+            continue;
+        }
+        // Footnote definition `[^id]: body` -> a flow `=== note {#id}` block so the
+        // matching `[^id]` reference resolves at build time (§5.2). Continuation
+        // lines (indented) are folded into the body.
+        const fn = /^\[\^([^\]]+)\]:\s?(.*)$/.exec(line);
+        if (fn) {
+            const body = fn[2].trim() ? [fn[2].trim()] : [];
+            let j = i + 1;
+            for (; j < lines.length; j++) {
+                if (/^\s{2,}\S/.test(lines[j]))
+                    body.push(lines[j].replace(/^\s+/, ""));
+                else if (lines[j].trim() === "")
+                    break;
+                else
+                    break;
+            }
+            emitBlock(out, "note", `{#${fn[1].trim()}}`, body.map(autolinks), ids);
+            i = j;
+            continue;
+        }
+        // Blockquote -> === note (flow). Strips one `>` level per line.
+        if (/^\s*>/.test(line)) {
+            const body = [];
+            while (i < lines.length && /^\s*>/.test(lines[i])) {
+                body.push(lines[i].replace(/^\s*>\s?/, ""));
+                i++;
+            }
+            emitBlock(out, "note", "", body, ids);
+            continue;
+        }
+        // GFM pipe table -> === table (visual body).
+        if (line.includes("|") && i + 1 < lines.length && TABLE_SEP.test(lines[i + 1]) && line.trim() !== "") {
+            const body = [line];
+            let j = i + 1;
+            body.push(lines[j]); // separator
+            j++;
+            while (j < lines.length && lines[j].includes("|") && lines[j].trim() !== "") {
+                body.push(lines[j]);
+                j++;
+            }
+            emitBlock(out, "table", "", body, ids);
+            i = j;
+            continue;
+        }
+        // ATX heading: pin an explicit id when it contains inline code. GEML's slug
+        // rule (§4) drops code-span content, but a Markdown TOC was authored against
+        // GitHub-style anchors (which keep it), so headings like `## 3. \`.x\` 文档`
+        // would otherwise break their links. Pinning the GitHub slug keeps both sides
+        // in agreement.
+        const atx = /^(#{1,6})\s+(.*?)\s*$/.exec(line);
+        if (atx && atx[2].includes("`") && !/\{[^}]*\}\s*$/.test(atx[2])) {
+            const id = githubSlug(atx[2]);
+            if (id) {
+                out.push(`${atx[1]} ${atx[2]} {#${id}}`);
+                i++;
+                continue;
+            }
+        }
+        // Inline pass: rewrite autolinks to GEML links (outside code spans).
+        const text = autolinks(line);
+        // Raw HTML note — ignore `<…>` that sits inside an inline code span.
+        if (/<[a-zA-Z/]/.test(text.replace(/`[^`]*`/g, ""))) {
+            notes.push(`raw HTML kept as text at line ${i + 1}: ${line.trim().slice(0, 40)}`);
+        }
+        // Everything else (ATX headings, lists, paragraphs, blanks) is valid GEML.
+        out.push(text);
+        i++;
+    }
+    let geml = out.join("\n");
+    if (!geml.endsWith("\n"))
+        geml += "\n";
+    return { geml, notes };
+}

package/dist/geml.d.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { type Value } from "./attrs.js";
+import { type Inline } from "./inline.js";
+import { type TableModel } from "./table.js";
+import { type ChartModel } from "./chart.js";
+export { type Value } from "./attrs.js";
+export { type Inline } from "./inline.js";
+export { type TableModel } from "./table.js";
+export { mdToGeml, type ConvertResult } from "./from-md.js";
+export { renderHtml, type RenderOptions } from "./render.js";
+export { serialize } from "./serialize.js";
+export { gemlToMd } from "./to-md.js";
+export type BodyMode = "raw" | "flow" | "data";
+export interface ListItem {
+    text: string;
+    inlines: Inline[];
+    checked?: boolean;
+    children?: Block[];
+}
+export type Block = {
+    kind: "heading";
+    level: number;
+    text: string;
+    inlines: Inline[];
+    id?: string;
+    classes: string[];
+    attrs: Record<string, Value>;
+    hidden?: boolean;
+} | {
+    kind: "paragraph";
+    text: string;
+    inlines: Inline[];
+} | {
+    kind: "list";
+    ordered: boolean;
+    start?: number;
+    loose?: boolean;
+    items: ListItem[];
+} | {
+    kind: "hidden";
+    text: string;
+} | {
+    kind: "block";
+    type: string;
+    mode: BodyMode;
+    id?: string;
+    classes: string[];
+    attrs: Record<string, Value>;
+    raw?: string[];
+    children?: Block[];
+    data?: Record<string, Value>;
+    table?: TableModel;
+    chart?: ChartModel;
+    hidden?: boolean;
+};
+export interface Diagnostic {
+    severity: "error" | "warning";
+    message: string;
+    line: number;
+}
+export interface Document {
+    kind: "document";
+    children: Block[];
+    ids: string[];
+    diagnostics: Diagnostic[];
+}
+export interface ParseOptions {
+    resolveDoc?: (doc: string) => string | null;
+}
+export declare function parse(source: string, opts?: ParseOptions): Document;