ironmark 1.12.3 → 2.0.0

package/README.md

@@ -6,159 +6,144 @@ Fast Markdown parser written in Rust with **zero third-party** parsing dependenc
 
 ## Table of Contents
 
-- [Configuration](#configuration)
-  - [Extensions](#extensions)
-  - [Security](#security)
-  - [Other Options](#other-options)
+- [Quick start](#quick-start)
+- [Which function should I use?](#which-function-should-i-use)
 - [JavaScript / TypeScript](#javascript--typescript)
   - [Node.js](#nodejs)
-  - [AST Output](#ast-output)
-  - [HTML to Markdown](#html-to-markdown)
-  - [AST to Markdown](#ast-to-markdown)
+  - [Markdown → HTML](#markdown--html)
+  - [Markdown → AST](#markdown--ast)
+  - [Markdown → AST → Markdown](#markdown--ast--markdown)
+  - [Safe HTML rendering](#safe-html-rendering)
   - [ANSI Terminal Output](#ansi-terminal-output)
+  - [HTML to Markdown](#html-to-markdown)
   - [Browser / Bundler](#browser--bundler)
+  - [Using ironmark in AI pipelines](#using-ironmark-in-ai-pipelines)
+  - [Presets](#presets)
+  - [Introspection helpers](#introspection-helpers)
+  - [Utility functions](#utility-functions)
+- [Configuration](#configuration)
+  - [Extensions](#extensions)
+  - [Security](#security)
+  - [Other Options](#other-options)
 - [CLI](#cli)
 - [Rust](#rust)
 - [C / C++](#c--c++)
 - [Benchmarks](#benchmarks)
 - [Development](#development)
 
-## Configuration
+## Quick start
 
-### Extensions (default `true`)
-
-| Option              | JS (`camelCase`)           | Rust (`snake_case`)           | Description                                            |
-| ------------------- | -------------------------- | ----------------------------- | ------------------------------------------------------ |
-| Hard breaks         | `hardBreaks`               | `hard_breaks`                 | Every newline becomes `<br />`                         |
-| Highlight           | `enableHighlight`          | `enable_highlight`            | `==text==` → `<mark>`                                  |
-| Strikethrough       | `enableStrikethrough`      | `enable_strikethrough`        | `~~text~~` → `<del>`                                   |
-| Underline           | `enableUnderline`          | `enable_underline`            | `++text++` → `<u>`                                     |
-| Tables              | `enableTables`             | `enable_tables`               | Pipe table syntax                                      |
-| Autolink            | `enableAutolink`           | `enable_autolink`             | Bare URLs & emails → `<a>`                             |
-| Task lists          | `enableTaskLists`          | `enable_task_lists`           | `- [ ]` / `- [x]` checkboxes                           |
-| Indented code       | `enableIndentedCodeBlocks` | `enable_indented_code_blocks` | 4-space indent → `<pre><code>`                         |
-| Wiki links          | `enableWikiLinks`          | `enable_wiki_links`           | `[[page]]` → `<a href="page">`                         |
-| LaTeX math          | `enableLateXMath`          | `enable_latex_math`           | `$inline$` and `$$display$$` → `<span class="math-…">` |
-| Heading IDs         | `enableHeadingIds`         | `enable_heading_ids`          | Auto `id=` on headings from slugified text             |
-| Heading anchors     | `enableHeadingAnchors`     | `enable_heading_anchors`      | `<a class="anchor">` inside each heading (implies IDs) |
-| Permissive headings | `permissiveAtxHeaders`     | `permissive_atx_headers`      | Allow `#Heading` without space after `#`               |
-
-### Security
+```bash
+npm install ironmark
+# or
+pnpm add ironmark
+```
 
-| Option           | JS (`camelCase`) | Rust (`snake_case`) | Default        | Description                                                        |
-| ---------------- | ---------------- | ------------------- | -------------- | ------------------------------------------------------------------ |
-| Disable raw HTML | `disableRawHtml` | `disable_raw_html`  | `false`        | Escape **all** HTML blocks and inline HTML                         |
-| No HTML blocks   | `noHtmlBlocks`   | `no_html_blocks`    | `false`        | Escape block-level HTML only (more granular than `disableRawHtml`) |
-| No HTML spans    | `noHtmlSpans`    | `no_html_spans`     | `false`        | Escape inline HTML only                                            |
-| Tag filter       | `tagFilter`      | `tag_filter`        | `false`        | GFM tag filter: escape `<script>`, `<iframe>`, etc.                |
-| Max nesting      | —                | `max_nesting_depth` | `128`          | Limit blockquote/list nesting depth (DoS prevention)               |
-| Max input size   | —                | `max_input_size`    | `0` (no limit) | Truncate input beyond this byte count                              |
+```ts
+import { renderHtml, parseMarkdown } from "ironmark";
 
-> In the WASM build, `max_nesting_depth` is fixed at `128` and `max_input_size` at `10 MB`.
+// Markdown → HTML
+const html = renderHtml("# Hello\n\n**World**");
 
-Dangerous URI schemes (`javascript:`, `vbscript:`, `data:` except `data:image/…`) are **always** stripped from link and image destinations, regardless of options.
+// Markdown → AST (parsed JavaScript object)
+const ast = parseMarkdown("# Hello\n\n**World**");
+```
 
-### Other Options
+## Which function should I use?
 
-| Option              | JS (`camelCase`)     | Rust (`snake_case`)   | Default | Description                                       |
-| ------------------- | -------------------- | --------------------- | ------- | ------------------------------------------------- |
-| Collapse whitespace | `collapseWhitespace` | `collapse_whitespace` | `false` | Collapse runs of spaces/tabs in text to one space |
+| Goal                            | Function                                            |
+| ------------------------------- | --------------------------------------------------- |
+| Render Markdown to HTML         | `renderHtml(input, options?)`                       |
+| Parse Markdown to AST object    | `parseMarkdown(input, options?)`                    |
+| Normalize / round-trip Markdown | `parseMarkdown()` + `renderMarkdown()`              |
+| Terminal / CLI output           | `renderAnsiTerminal(input, options?, ansiOptions?)` |
+| Convert HTML back to Markdown   | `htmlToMarkdown(html)` / `parseHtmlToAst(html)`     |
 
 ## JavaScript / TypeScript
 
-```bash
-npm install ironmark
-# or
-pnpm add ironmark
-```
-
 ### Node.js
 
 WASM is embedded and loaded synchronously — no `init()` needed:
 
 ```ts
-import { parse } from "ironmark";
-
-const html = parse("# Hello\n\nThis is **fast**.");
+import { renderHtml, parseMarkdown } from "ironmark";
 
-// safe mode for untrusted input
-const safe = parse(userInput, { disableRawHtml: true });
+const html = renderHtml("# Hello\n\nThis is **fast**.");
+const ast = parseMarkdown("# Hello");
 ```
 
-### AST Output
-
-Use `parseToAst()` when you need the block-level document structure instead of rendered HTML.
+### Markdown → HTML
 
 ```ts
-import { parseToAst } from "ironmark";
+import { renderHtml } from "ironmark";
 
-const astJson = parseToAst("# Hello\n\n- [x] done");
-const ast = JSON.parse(astJson);
+const html = renderHtml("# Hello\n\nThis is **fast**.");
 ```
 
-`parseToAst()` returns a JSON string for portability across JS runtimes and WASM boundaries.
-
-### HTML to Markdown
+### Markdown → AST
 
-Convert HTML back to Markdown syntax using `htmlToMarkdown()`. Useful for importing content from HTML sources or round-trip conversion.
+`parseMarkdown()` returns a parsed JavaScript array — no `JSON.parse()` needed.
 
 ```ts
-import { htmlToMarkdown } from "ironmark";
+import { parseMarkdown } from "ironmark";
 
-const md = htmlToMarkdown("<h1>Hello</h1><p><strong>Bold</strong> text</p>");
-// Returns: "# Hello\n\n**Bold** text"
-
-// Preserve unknown HTML tags (e.g., <sup>, <sub>) as raw HTML in output
-const md = htmlToMarkdown("<p>H<sub>2</sub>O</p>", true);
-// Returns: "H<sub>2</sub>O"
+const ast = parseMarkdown("# Hello\n\n- [x] done");
+// ast is a JavaScript array of block nodes
+console.log(ast[0]); // { t: "Heading", level: 1, ... }
 ```
 
-For AST access, use `parseHtmlToAst()`:
+### Markdown → AST → Markdown
 
 ```ts
-import { parseHtmlToAst } from "ironmark";
+import { parseMarkdown, renderMarkdown } from "ironmark";
 
-const astJson = parseHtmlToAst("<h1>Hello</h1><p>World</p>");
-const ast = JSON.parse(astJson);
+const ast = parseMarkdown("**Hello**");
+const md = renderMarkdown(ast);
+// Returns: "**Hello**"
 ```
 
-### AST to Markdown
+### Safe HTML rendering
 
-Render an AST back to Markdown syntax using `renderMarkdown()`. Combined with `parseToAst()` or `parseHtmlToAst()`, this enables round-trip conversion.
+Use `safe: true` for **any untrusted input** — it disables raw HTML passthrough and enables the GFM tag filter.
 
 ```ts
-import { parseToAst, renderMarkdown } from "ironmark";
+import { renderHtml } from "ironmark";
 
-const ast = parseToAst("# Hello\n\n**World**");
-const md = renderMarkdown(ast);
-// Returns: "# Hello\n\n**World**"
+// Simple safe flag
+const html = renderHtml(userInput, { safe: true });
+
+// Or use the built-in preset
+const html = renderHtml(userInput, { preset: "safe" });
 ```
 
+What `safe: true` does:
+
+- Sets `disableRawHtml: true` — all inline and block HTML is escaped
+- Sets `tagFilter: true` — dangerous tags (`<script>`, `<iframe>`, etc.) are escaped
+
+Dangerous URI schemes (`javascript:`, `vbscript:`, `data:` except `data:image/…`) are **always** stripped from link destinations regardless of options.
+
 ### ANSI Terminal Output
 
-Use `renderAnsi()` to render Markdown as coloured terminal output (ANSI 256-colour escape codes). Useful for CLI tools, terminal UIs, or any environment with a TTY.
+Use `renderAnsiTerminal()` to render Markdown as coloured terminal output (ANSI 256-colour escape codes).
 
 ````ts
-import { renderAnsi } from "ironmark";
+import { renderAnsiTerminal } from "ironmark";
 
-// Render with defaults (width 80, colour enabled)
-const ansi = renderAnsi("# Hello\n\n**bold** and `code`");
+// Defaults: width 80, color enabled
+const ansi = renderAnsiTerminal("# Hello\n\n**bold** and `code`");
 process.stdout.write(ansi);
 
-// Custom terminal width and line numbers in code blocks
-const ansi = renderAnsi(
+// Custom options
+const ansi = renderAnsiTerminal(
   "# Hello\n\n```rust\nfn main() {}\n```",
-  {}, // parse options (same as parse())
+  {},
   { width: 120, lineNumbers: true },
 );
 process.stdout.write(ansi);
 
-// With padding — adds horizontal spacing on both sides
-const ansi = renderAnsi("# Hello\n\n> A quote", {}, { padding: 2 });
-process.stdout.write(ansi);
-
-// Plain text — strips all ANSI codes (useful for piping to files)
-const plain = renderAnsi("# Hello\n\n> quote", {}, { color: false });
+// Plain text — no ANSI codes (useful for piping to files)
+const plain = renderAnsiTerminal("# Hello", {}, { color: false });
 ````
 
 #### ANSI options
@@ -170,44 +155,222 @@ const plain = renderAnsi("# Hello\n\n> quote", {}, { color: false });
 | `lineNumbers` | `boolean` | `false` | Show line numbers in fenced code blocks.                                                      |
 | `padding`     | `number`  | `0`     | Horizontal padding added to both sides of each line, plus ⌈padding/2⌉ blank lines at the top. |
 
+### HTML to Markdown
+
+Convert HTML back to Markdown syntax using `htmlToMarkdown()`.
+
+```ts
+import { htmlToMarkdown } from "ironmark";
+
+const md = htmlToMarkdown("<h1>Hello</h1><p><strong>Bold</strong> text</p>");
+// Returns: "# Hello\n\n**Bold** text"
+
+// Preserve unknown HTML tags (e.g. <sup>, <sub>) as raw HTML in output
+const md = htmlToMarkdown("<p>H<sub>2</sub>O</p>", true);
+// Returns: "H<sub>2</sub>O"
+```
+
+For AST access, use `parseHtmlToAst()`:
+
+```ts
+import { parseHtmlToAst, renderMarkdown } from "ironmark";
+
+const ast = parseHtmlToAst("<h1>Hello</h1><p>World</p>");
+const md = renderMarkdown(ast);
+```
+
 ### Browser / Bundler
 
-Call `init()` once before using `parse()`. It's idempotent and optionally accepts a custom `.wasm` URL.
+Call `init()` once before using any function. It's idempotent and optionally accepts a custom `.wasm` URL.
 
 ```ts
-import { init, parse } from "ironmark";
+import { init, renderHtml, parseMarkdown } from "ironmark";
 
 await init();
 
-const html = parse("# Hello\n\nThis is **fast**.");
+const html = renderHtml("# Hello\n\nThis is **fast**.");
+const ast = parseMarkdown("# Hello");
 ```
 
 #### Vite
 
 ```ts
-import { init, parse } from "ironmark";
+import { init, renderHtml } from "ironmark";
 import wasmUrl from "ironmark/ironmark.wasm?url";
 
 await init(wasmUrl);
 
-const html = parse("# Hello\n\nThis is **fast**.");
+const html = renderHtml("# Hello\n\nThis is **fast**.");
 ```
 
+### Using ironmark in AI pipelines
+
+ironmark is designed to be a reliable, deterministic parsing layer for AI agents and code generation tools.
+
+**Recommended pattern for agents:**
+
+```ts
+import { parseMarkdown, renderHtml, renderMarkdown, getCapabilities } from "ironmark";
+
+// 1. Inspect capabilities at startup
+const caps = getCapabilities();
+// { astSchemaVersion: "2", formats: [...], presets: [...] }
+
+// 2. Parse with deterministic options
+const ast = parseMarkdown(content, { preset: "llm" });
+
+// 3. Render or transform
+const html = renderHtml(content, { preset: "llm" });
+const normalized = renderMarkdown(ast);
+```
+
+**The `llm` preset** produces deterministic, structure-first output:
+
+- Disables autolinks, wiki links, math, hard breaks (ambiguous in AI-generated text)
+- Enables heading IDs and whitespace normalization
+- Disables raw HTML passthrough (safe by default)
+
+```ts
+import { parseMarkdown, extractHeadings, summarizeAst } from "ironmark";
+
+const ast = parseMarkdown(content, { preset: "llm" });
+
+// Extract document structure
+const headings = extractHeadings(ast);
+// [{ level: 1, text: "Introduction", id: "introduction" }, ...]
+
+// Summarize node types
+const summary = summarizeAst(ast);
+// { blockCount: 5, nodeCounts: { Heading: 2, Paragraph: 3, ... } }
+```
+
+### Presets
+
+Named presets configure multiple options at once. Explicit options always override the preset.
+
+| Preset      | Description                                                                                        |
+| ----------- | -------------------------------------------------------------------------------------------------- |
+| `"default"` | All extensions enabled. Current default behavior.                                                  |
+| `"safe"`    | Disables raw HTML, enables GFM tag filter. Use for untrusted input.                                |
+| `"strict"`  | CommonMark-only: disables extensions and permissive behaviors.                                     |
+| `"llm"`     | Deterministic, stable output for AI pipelines. Disables ambiguous extensions, enables heading IDs. |
+
+```ts
+import { renderHtml, parseMarkdown } from "ironmark";
+
+// Use a preset
+const html = renderHtml(content, { preset: "safe" });
+
+// Presets compose with explicit options (explicit wins)
+const html = renderHtml(content, { preset: "llm", enableTables: false });
+```
+
+### Introspection helpers
+
+These functions return stable machine-readable metadata. Useful for agents and tooling to discover available features at runtime.
+
+```ts
+import { getCapabilities, getAstSchemaVersion, getDefaultOptions, getPresets } from "ironmark";
+
+// What does this build support?
+const caps = getCapabilities();
+// {
+//   astSchemaVersion: "1",
+//   formats: ["html", "ast", "markdown", "ansi"],
+//   presets: ["default", "safe", "strict", "llm"],
+//   extensions: [...],
+//   security: [...]
+// }
+
+// What is the current AST schema version?
+const version = getAstSchemaVersion(); // "1"
+
+// What are the resolved defaults for every option?
+const defaults = getDefaultOptions();
+
+// What options does each preset set?
+const presets = getPresets();
+console.log(presets.llm);
+```
+
+### Utility functions
+
+```ts
+import { parseMarkdown, extractHeadings, summarizeAst } from "ironmark";
+
+const ast = parseMarkdown("# Hello\n\n## World\n\nA paragraph.");
+
+// Extract heading structure
+const headings = extractHeadings(ast);
+// [
+//   { level: 1, text: "Hello", id: "hello" },
+//   { level: 2, text: "World", id: "world" },
+// ]
+
+// Count node types
+const summary = summarizeAst(ast);
+// { blockCount: 3, nodeCounts: { Heading: 2, Paragraph: 1 } }
+```
+
+## Configuration
+
+### Extensions (default `true`)
+
+| Option              | JS (`camelCase`)           | Rust (`snake_case`)           | Description                                            |
+| ------------------- | -------------------------- | ----------------------------- | ------------------------------------------------------ |
+| Hard breaks         | `hardBreaks`               | `hard_breaks`                 | Every newline becomes `<br />`                         |
+| Highlight           | `enableHighlight`          | `enable_highlight`            | `==text==` → `<mark>`                                  |
+| Strikethrough       | `enableStrikethrough`      | `enable_strikethrough`        | `~~text~~` → `<del>`                                   |
+| Underline           | `enableUnderline`          | `enable_underline`            | `++text++` → `<u>`                                     |
+| Tables              | `enableTables`             | `enable_tables`               | Pipe table syntax                                      |
+| Autolink            | `enableAutolink`           | `enable_autolink`             | Bare URLs & emails → `<a>`                             |
+| Task lists          | `enableTaskLists`          | `enable_task_lists`           | `- [ ]` / `- [x]` checkboxes                           |
+| Indented code       | `enableIndentedCodeBlocks` | `enable_indented_code_blocks` | 4-space indent → `<pre><code>`                         |
+| Wiki links          | `enableWikiLinks`          | `enable_wiki_links`           | `[[page]]` → `<a href="page">`                         |
+| LaTeX math          | `enableLatexMath`          | `enable_latex_math`           | `$inline$` and `$$display$$` → `<span class="math-…">` |
+| Heading IDs         | `enableHeadingIds`         | `enable_heading_ids`          | Auto `id=` on headings from slugified text             |
+| Heading anchors     | `enableHeadingAnchors`     | `enable_heading_anchors`      | `<a class="anchor">` inside each heading (implies IDs) |
+| Permissive headings | `permissiveAtxHeaders`     | `permissive_atx_headers`      | Allow `#Heading` without space after `#`               |
+
+### Security
+
+| Option           | JS (`camelCase`) | Rust (`snake_case`) | Default        | Description                                                        |
+| ---------------- | ---------------- | ------------------- | -------------- | ------------------------------------------------------------------ |
+| Safe mode        | `safe`           | —                   | `false`        | Shorthand: sets `disableRawHtml: true` and `tagFilter: true`       |
+| Disable raw HTML | `disableRawHtml` | `disable_raw_html`  | `false`        | Escape **all** HTML blocks and inline HTML                         |
+| No HTML blocks   | `noHtmlBlocks`   | `no_html_blocks`    | `false`        | Escape block-level HTML only (more granular than `disableRawHtml`) |
+| No HTML spans    | `noHtmlSpans`    | `no_html_spans`     | `false`        | Escape inline HTML only                                            |
+| Tag filter       | `tagFilter`      | `tag_filter`        | `false`        | GFM tag filter: escape `<script>`, `<iframe>`, etc.                |
+| Max nesting      | —                | `max_nesting_depth` | `128`          | Limit blockquote/list nesting depth (DoS prevention)               |
+| Max input size   | —                | `max_input_size`    | `0` (no limit) | Truncate input beyond this byte count                              |
+
+> In the WASM build, `max_nesting_depth` is fixed at `128` and `max_input_size` at `10 MB`.
+
+Dangerous URI schemes (`javascript:`, `vbscript:`, `data:` except `data:image/…`) are **always** stripped from link and image destinations, regardless of options.
+
+### Other Options
+
+| Option              | JS (`camelCase`)     | Rust (`snake_case`)   | Default | Description                                       |
+| ------------------- | -------------------- | --------------------- | ------- | ------------------------------------------------- |
+| Collapse whitespace | `collapseWhitespace` | `collapse_whitespace` | `false` | Collapse runs of spaces/tabs in text to one space |
+| Preset              | `preset`             | —                     | —       | Apply a named option preset (JS only)             |
+| Deterministic       | `deterministic`      | —                     | `false` | Normalize whitespace for stable output (JS only)  |
+
 ## CLI
 
-Render Markdown as coloured terminal output. Two ways to install:
+Render Markdown as HTML, ANSI terminal output, or an AST. Default format is `html`.
 
 ### npm
 
 ```bash
-npx ironmark --ansi README.md
+npx ironmark README.md
 ```
 
 Or install globally:
 
 ```bash
 npm install -g ironmark
-ironmark --ansi README.md
+ironmark README.md
 ```
 
 ### Rust
@@ -216,47 +379,72 @@ Native binary — faster startup, auto-detects terminal width via `$COLUMNS` / `
 
 ```bash
 cargo install ironmark --features cli
-ironmark --ansi README.md
+ironmark README.md
 ```
 
 ### Options
 
-Both CLIs support the same flags (the npm CLI requires `--ansi` as the first flag):
+Both CLIs support the same flags:
 
 ```text
-OPTIONS:
+OPTIONS (all formats):
+    --format <html|ansi|ast>    Output format; ast also accepts 'json' (default: html)
+    --preset <name>             Apply a named option preset: default, safe, strict, llm
+    --safe                      Alias for --preset safe
+    --no-hard-breaks            Don't turn soft newlines into hard line breaks
+    --no-tables                 Disable pipe table syntax
+    --no-highlight              Disable ==highlight== syntax
+    --no-strikethrough          Disable ~~strikethrough~~ syntax
+    --no-underline              Disable ++underline++ syntax
+    --no-autolink               Disable bare URL auto-linking
+    --no-task-lists             Disable - [x] task list syntax
+    --math                      Enable $inline$ and $$display$$ math
+    --wiki-links                Enable [[wiki link]] syntax
+    --capabilities              Print machine-readable capabilities JSON and exit
+    --default-options           Print resolved default options JSON and exit
+    --list-presets              Print all presets and exit
+    --max-size N                Truncate input to N bytes (Rust only)
+    -h, --help                  Print this help and exit
+    -V, --version               Print version and exit
+
+OPTIONS (ansi format only):
     --width N            Terminal column width (default: auto-detect, fallback 80)
-    --padding N          Horizontal padding added to both sides of each line, plus ceil(padding/2) blank lines at the top (default: 0)
+    --padding N          Horizontal padding added to both sides of each line (default: 0)
     --no-color           Disable ANSI escape codes (plain text)
     -n, --line-numbers   Show line numbers in fenced code blocks
-    --no-hard-breaks     Don't turn soft newlines into hard line breaks
-    --no-tables          Disable pipe table syntax
-    --no-highlight       Disable ==highlight== syntax
-    --no-strikethrough   Disable ~~strikethrough~~ syntax
-    --no-underline       Disable ++underline++ syntax
-    --no-autolink        Disable bare URL auto-linking
-    --no-task-lists      Disable - [x] task list syntax
-    --math               Enable $inline$ and $$display$$ math
-    --wiki-links         Enable [[wiki link]] syntax
-    --max-size N         Truncate input to N bytes (Rust only)
-    -h, --help           Print this help and exit
-    -V, --version        Print version and exit
 ```
 
 ### Examples
 
 ```bash
-# npm
-npx ironmark --ansi README.md
-npx ironmark --ansi --width 120 README.md
-echo '# Hello' | npx ironmark --ansi
-npx ironmark --ansi --no-color README.md | less
+# Render as HTML (default)
+echo '# Hello' | npx ironmark
+npx ironmark README.md
+
+# Safe mode for untrusted content
+npx ironmark --safe README.md
+npx ironmark --preset safe README.md
+
+# LLM-optimized output
+npx ironmark --preset llm README.md
+
+# Render as ANSI terminal output
+npx ironmark --format ansi README.md
+npx ironmark --format ansi --width 120 README.md
+npx ironmark --format ansi --no-color README.md | less
+
+# Render as AST (JSON)
+npx ironmark --format ast README.md
+
+# Inspect capabilities
+npx ironmark --capabilities
+npx ironmark --list-presets
 
 # Rust (after cargo install ironmark --features cli)
-ironmark --ansi README.md
-ironmark --ansi --width 120 README.md
-echo '# Hello' | ironmark --ansi
-cat doc.md | ironmark --ansi --math --wiki-links
+echo '# Hello' | ironmark
+ironmark --format ansi README.md
+ironmark --format ansi --width 120 README.md
+cat doc.md | ironmark --format ansi --math --wiki-links
 ```
 
 ## Rust
@@ -266,21 +454,21 @@ cargo add ironmark
 ```
 
 ```rust
-use ironmark::{parse, ParseOptions};
+use ironmark::{render_html, ParseOptions};
 
 fn main() {
     // with defaults
-    let html = parse("# Hello\n\nThis is **fast**.", &ParseOptions::default());
+    let html = render_html("# Hello\n\nThis is **fast**.", &ParseOptions::default());
 
     // with custom options
-    let html = parse("line one\nline two", &ParseOptions {
+    let html = render_html("line one\nline two", &ParseOptions {
         hard_breaks: false,
         enable_strikethrough: false,
         ..Default::default()
     });
 
     // safe mode for untrusted input
-    let html = parse("<script>alert(1)</script>", &ParseOptions {
+    let html = render_html("<script>alert(1)</script>", &ParseOptions {
         disable_raw_html: true,
         max_input_size: 1_000_000, // 1 MB
         ..Default::default()
@@ -293,10 +481,10 @@ fn main() {
 `parse_to_ast()` returns the typed Rust AST (`Block`) directly:
 
 ```rust
-use ironmark::{Block, ParseOptions, parse_to_ast};
+use ironmark::{Block, ParseOptions, parse_markdown};
 
 fn main() {
-    let ast = parse_to_ast("# Hello", &ParseOptions::default());
+    let ast = parse_markdown("# Hello", &ParseOptions::default());
 
     match ast {
         Block::Document { children } => {
@@ -368,10 +556,10 @@ fn main() {
 Render an AST back to Markdown syntax:
 
 ```rust
-use ironmark::{parse_to_ast, render_markdown, ParseOptions};
+use ironmark::{parse_markdown, render_markdown, ParseOptions};
 
 fn main() {
-    let ast = parse_to_ast("# Hello\n\n**World**", &ParseOptions::default());
+    let ast = parse_markdown("# Hello\n\n**World**", &ParseOptions::default());
     let md = render_markdown(&ast);
     // Returns: "# Hello\n\n**World**"
 }
@@ -379,18 +567,18 @@ fn main() {
 
 ### ANSI Terminal Output
 
-`render_ansi()` renders Markdown as ANSI-coloured terminal output. Pass `Some(&AnsiOptions { .. })` to control width, colour, and line numbers, or `None` for defaults.
+`render_ansi_terminal()` renders Markdown as ANSI-coloured terminal output. Pass `Some(&AnsiOptions { .. })` to control width, colour, and line numbers, or `None` for defaults.
 
 ````rust
-use ironmark::{AnsiOptions, ParseOptions, render_ansi};
+use ironmark::{AnsiOptions, ParseOptions, render_ansi_terminal};
 
 fn main() {
     // Defaults — width 80, colour enabled
-    let out = render_ansi("# Hello\n\n**bold** and `code`", &ParseOptions::default(), None);
+    let out = render_ansi_terminal("# Hello\n\n**bold** and `code`", &ParseOptions::default(), None);
     print!("{out}");
 
     // Custom options — 120 columns, line numbers in code blocks
-    let out = render_ansi(
+    let out = render_ansi_terminal(
         "# Hello\n\n```rust\nfn main() {}\n```",
         &ParseOptions::default(),
         Some(&AnsiOptions { width: 120, line_numbers: true, ..AnsiOptions::default() }),
@@ -398,7 +586,7 @@ fn main() {
     print!("{out}");
 
     // With padding — adds horizontal spacing on both sides
-    let out = render_ansi(
+    let out = render_ansi_terminal(
         "# Hello\n\n> A quote",
         &ParseOptions::default(),
         Some(&AnsiOptions { padding: 2, ..AnsiOptions::default() }),
@@ -406,7 +594,7 @@ fn main() {
     print!("{out}");
 
     // Plain text — no ANSI codes (e.g. for writing to a file)
-    let plain = render_ansi(
+    let plain = render_ansi_terminal(
         "# Hello",
         &ParseOptions::default(),
         Some(&AnsiOptions { color: false, ..AnsiOptions::default() }),
@@ -452,7 +640,7 @@ cc -o example example.c -L target/release -l ironmark \
 #include <stdio.h>
 
 int main(void) {
-    char *html = ironmark_parse("# Hello\n\nThis is **fast**.");
+    char *html = ironmark_render_html("# Hello\n\nThis is **fast**.");
     if (html) {
         printf("%s\n", html);
         ironmark_free(html);
@@ -461,7 +649,7 @@ int main(void) {
 }
 ```
 
-**Memory contract**: `ironmark_parse` returns a heap-allocated string. You **must** free it with `ironmark_free`. Passing any other pointer to `ironmark_free` is undefined behaviour. Both functions are null-safe: `ironmark_parse(NULL)` returns `NULL`; `ironmark_free(NULL)` is a no-op.
+**Memory contract**: `ironmark_render_html` returns a heap-allocated string. You **must** free it with `ironmark_free`. Passing any other pointer to `ironmark_free` is undefined behaviour. Both functions are null-safe: `ironmark_render_html(NULL)` returns `NULL`; `ironmark_free(NULL)` is a no-op.
 
 Parsing always uses the default `ParseOptions` (all extensions enabled, `disable_raw_html` off). Options are not yet configurable through the C API.