ironmark 1.8.1 → 1.10.0

package/README.md

@@ -84,6 +84,37 @@ const ast = JSON.parse(astJson);
 
 `parseToAst()` returns a JSON string for portability across JS runtimes and WASM boundaries.
 
+### 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.
+
+````ts
+import { renderAnsi } from "ironmark";
+
+// Render with defaults (width 80, colour enabled)
+const ansi = renderAnsi("# Hello\n\n**bold** and `code`");
+process.stdout.write(ansi);
+
+// Custom terminal width and line numbers in code blocks
+const ansi = renderAnsi(
+  "# Hello\n\n```rust\nfn main() {}\n```",
+  {}, // parse options (same as parse())
+  { width: 120, lineNumbers: true },
+);
+process.stdout.write(ansi);
+
+// Plain text — strips all ANSI codes (useful for piping to files)
+const plain = renderAnsi("# Hello\n\n> quote", {}, { color: false });
+````
+
+#### ANSI options
+
+| Option        | Type      | Default | Description                                                                     |
+| ------------- | --------- | ------- | ------------------------------------------------------------------------------- |
+| `width`       | `number`  | `80`    | Column width for word-wrap, heading underlines, rule length. `0` = use default. |
+| `color`       | `boolean` | `true`  | Emit ANSI colour codes. `false` = plain text output.                            |
+| `lineNumbers` | `boolean` | `false` | Show line numbers in fenced code blocks.                                        |
+
 ### Browser / Bundler
 
 Call `init()` once before using `parse()`. It's idempotent and optionally accepts a custom `.wasm` URL.
@@ -107,6 +138,71 @@ await init(wasmUrl);
 const html = parse("# Hello\n\nThis is **fast**.");
 ```
 
+## CLI
+
+Render Markdown as coloured terminal output. Two ways to install:
+
+### npm
+
+```bash
+npx ironmark --ansi README.md
+```
+
+Or install globally:
+
+```bash
+npm install -g ironmark
+ironmark --ansi README.md
+```
+
+### Rust
+
+Native binary — faster startup, auto-detects terminal width via `$COLUMNS` / `tput cols`.
+
+```bash
+cargo install ironmark --features cli
+ironmark --ansi README.md
+```
+
+### Options
+
+Both CLIs support the same flags (the npm CLI requires `--ansi` as the first flag):
+
+```text
+OPTIONS:
+    --width N            Terminal column width (default: auto-detect, fallback 80)
+    --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
+
+# 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
+```
+
 ## Rust
 
 ```bash
@@ -162,6 +258,43 @@ Exported AST types:
 - `TableData`
 - `TableAlignment`
 
+### 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.
+
+````rust
+use ironmark::{AnsiOptions, ParseOptions, render_ansi};
+
+fn main() {
+    // Defaults — width 80, colour enabled
+    let out = render_ansi("# Hello\n\n**bold** and `code`", &ParseOptions::default(), None);
+    print!("{out}");
+
+    // Custom options — 120 columns, line numbers in code blocks
+    let out = render_ansi(
+        "# Hello\n\n```rust\nfn main() {}\n```",
+        &ParseOptions::default(),
+        Some(&AnsiOptions { width: 120, line_numbers: true, ..AnsiOptions::default() }),
+    );
+    print!("{out}");
+
+    // Plain text — no ANSI codes (e.g. for writing to a file)
+    let plain = render_ansi(
+        "# Hello",
+        &ParseOptions::default(),
+        Some(&AnsiOptions { color: false, ..AnsiOptions::default() }),
+    );
+}
+````
+
+`AnsiOptions` fields:
+
+| Field          | Type    | Default | Description                                                                 |
+| -------------- | ------- | ------- | --------------------------------------------------------------------------- |
+| `width`        | `usize` | `80`    | Column width for word-wrap, heading underlines, rule length. `0` = disable. |
+| `color`        | `bool`  | `true`  | Emit ANSI 256-colour escape codes.                                          |
+| `line_numbers` | `bool`  | `false` | Show line numbers in fenced code blocks.                                    |
+
 ## C / C++
 
 The crate compiles to a static library (`libironmark.a`) that exposes two C functions. A header is provided at `include/ironmark.h`.
@@ -236,4 +369,4 @@ pnpm build
 
 ### Troubleshooting
 
-**`wasm32-unknown-unknown target not found`** or **`wasm-bindgen not found`** — run `pnpm setup:wasm` to install all prerequisites.
+**`wasm32-unknown-unknown target not found`** or **`wasm-bindgen not found`** — run `pnpm setup:wasm` to install all prerequisites

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ironmark",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "Very fast markdown parser in Rust, consumable from JavaScript/TypeScript via WebAssembly",
   "keywords": [
     "markdown",
@@ -17,11 +17,15 @@
     "type": "git",
     "url": "https://github.com/ph1p/ironmark.git"
   },
+  "bin": {
+    "ironmark": "wasm/cli.js"
+  },
   "files": [
     "wasm/pkg",
     "wasm/shared.js",
     "wasm/web.js",
     "wasm/node.js",
+    "wasm/cli.js",
     "wasm/index.d.ts",
     "README.md"
   ],

package/wasm/cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { renderAnsi } from "./node.js";
+
+const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
+const HELP = `ironmark — render Markdown as coloured terminal output
+
+USAGE:
+    ironmark --ansi [OPTIONS] [FILE...]
+
+    When no FILE is given, reads from stdin. Use '-' for stdin explicitly.
+
+OPTIONS:
+    --ansi               Render as ANSI-coloured terminal output (required)
+    --width N            Terminal column width (default: auto-detect, fallback 80)
+    --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
+    -h, --help           Print this help and exit
+    -V, --version        Print version and exit
+
+EXAMPLES:
+    npx ironmark --ansi README.md
+    npx ironmark --ansi --width 120 README.md
+    npx ironmark --ansi --no-color README.md | less
+    echo '# Hello' | npx ironmark --ansi
+    cat doc.md | npx ironmark --ansi --math --wiki-links
+`;
+
+const args = process.argv.slice(2);
+const files = [];
+const parseOptions = {};
+const ansiOptions = {};
+let ansiMode = false;
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case "-h":
+    case "--help":
+      process.stdout.write(HELP);
+      process.exit(0);
+      break;
+    case "-V":
+    case "--version":
+      console.log(`ironmark ${VERSION}`);
+      process.exit(0);
+      break;
+    case "--ansi":
+      ansiMode = true;
+      break;
+    case "--no-color":
+    case "--no-colour":
+      ansiOptions.color = false;
+      break;
+    case "-n":
+    case "--line-numbers":
+      ansiOptions.lineNumbers = true;
+      break;
+    case "--width": {
+      const val = args[++i];
+      if (val === undefined || Number.isNaN(Number(val))) {
+        console.error("error: --width requires a numeric value");
+        process.exit(2);
+      }
+      ansiOptions.width = Number(val);
+      break;
+    }
+    case "--no-hard-breaks":
+      parseOptions.hardBreaks = false;
+      break;
+    case "--no-tables":
+      parseOptions.enableTables = false;
+      break;
+    case "--no-highlight":
+      parseOptions.enableHighlight = false;
+      break;
+    case "--no-strikethrough":
+      parseOptions.enableStrikethrough = false;
+      break;
+    case "--no-underline":
+      parseOptions.enableUnderline = false;
+      break;
+    case "--no-autolink":
+      parseOptions.enableAutolink = false;
+      break;
+    case "--no-task-lists":
+      parseOptions.enableTaskLists = false;
+      break;
+    case "--math":
+      parseOptions.enableLatexMath = true;
+      break;
+    case "--wiki-links":
+      parseOptions.enableWikiLinks = true;
+      break;
+    default:
+      if (args[i].startsWith("--width=")) {
+        const val = Number(args[i].slice("--width=".length));
+        if (Number.isNaN(val)) {
+          console.error("error: --width requires a numeric value");
+          process.exit(2);
+        }
+        ansiOptions.width = val;
+      } else if (args[i].startsWith("-") && args[i] !== "-") {
+        console.error(`error: unknown flag: ${args[i]}`);
+        console.error("Run 'ironmark --help' for usage.");
+        process.exit(2);
+      } else {
+        files.push(args[i]);
+      }
+  }
+}
+
+if (!ansiMode) {
+  console.error("error: --ansi flag is required");
+  console.error("Run 'ironmark --help' for usage.");
+  process.exit(2);
+}
+
+// Auto-detect terminal width
+if (ansiOptions.width === undefined) {
+  ansiOptions.width = process.stdout.columns || 80;
+}
+
+let input = "";
+
+if (files.length === 0) {
+  input = readFileSync(0, "utf8");
+} else {
+  for (const file of files) {
+    if (file === "-") {
+      input += readFileSync(0, "utf8");
+    } else {
+      try {
+        input += readFileSync(file, "utf8");
+      } catch (err) {
+        console.error(`error: ${file}: ${err.message}`);
+        process.exit(1);
+      }
+    }
+  }
+}
+
+process.stdout.write(renderAnsi(input, parseOptions, ansiOptions));

package/wasm/index.d.ts

@@ -66,3 +66,49 @@ export declare function parse(markdown: MarkdownInput, options?: ParseOptions):
  * @returns JSON string representing the AST.
  */
 export declare function parseToAst(markdown: MarkdownInput, options?: ParseOptions): string;
+
+/**
+ * Options for the ANSI terminal renderer.
+ */
+export interface AnsiOptions {
+  /**
+   * Terminal column width for word-wrap, heading underlines, and thematic breaks.
+   * Set to `0` to disable all width-dependent formatting. Default: `80`.
+   */
+  width?: number;
+  /**
+   * Emit ANSI 256-colour escape codes. Set to `false` for plain-text output
+   * (e.g. when piping to a file or a non-colour terminal). Default: `true`.
+   */
+  color?: boolean;
+  /**
+   * Show line numbers in fenced code blocks, right-aligned to the total line
+   * count and separated from the code by a `│` border. Default: `false`.
+   */
+  lineNumbers?: boolean;
+}
+
+/**
+ * Render Markdown as ANSI-coloured terminal output.
+ *
+ * Produces a string containing ANSI 256-colour escape codes suitable for
+ * display in a terminal emulator. Headings, code blocks, inline code,
+ * blockquotes, tables, and inline formatting are all styled distinctly.
+ *
+ * @param markdown - Markdown source (string or binary).
+ * @param options - Optional parse options (same flags as `parse()`).
+ * @param ansiOptions - Optional ANSI rendering options (width, color, lineNumbers).
+ * @returns String with ANSI escape codes (or plain text when `color: false`).
+ *
+ * @example
+ * ```ts
+ * import { renderAnsi } from "ironmark";
+ * const out = renderAnsi("# Hello\n\n**bold** and `code`");
+ * process.stdout.write(out);
+ * ```
+ */
+export declare function renderAnsi(
+  markdown: MarkdownInput,
+  options?: ParseOptions,
+  ansiOptions?: AnsiOptions,
+): string;