ironmark 1.11.4 → 1.12.1

package/README.md

@@ -2,32 +2,46 @@
 
 [![CI](https://github.com/ph1p/ironmark/actions/workflows/ci.yml/badge.svg)](https://github.com/ph1p/ironmark/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/ironmark)](https://www.npmjs.com/package/ironmark) [![crates.io](https://img.shields.io/crates/v/ironmark)](https://crates.io/crates/ironmark)
 
-Fast Markdown to HTML/AST parser written in Rust with **zero third-party** parsing dependencies. Fully compliant with [CommonMark 0.31.2](https://spec.commonmark.org/0.31.2/) (652/652 spec tests pass). Available as a Rust crate and as an npm package via WebAssembly, with both HTML and AST output APIs.
-
-## Options
+Fast Markdown parser written in Rust with **zero third-party** parsing dependencies. Outputs HTML, AST, ANSI terminal, or Markdown. Fully compliant with [CommonMark 0.31.2](https://spec.commonmark.org/0.31.2/) (652/652 spec tests pass). Available as a Rust crate and as an npm package via WebAssembly.
+
+## Table of Contents
+
+- [Configuration](#configuration)
+  - [Extensions](#extensions)
+  - [Security](#security)
+  - [Other Options](#other-options)
+- [JavaScript / TypeScript](#javascript--typescript)
+  - [Node.js](#nodejs)
+  - [AST Output](#ast-output)
+  - [HTML to Markdown](#html-to-markdown)
+  - [AST to Markdown](#ast-to-markdown)
+  - [ANSI Terminal Output](#ansi-terminal-output)
+  - [Browser / Bundler](#browser--bundler)
+- [CLI](#cli)
+- [Rust](#rust)
+- [C / C++](#c--c++)
+- [Benchmarks](#benchmarks)
+- [Development](#development)
+
+## 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>` |
-
-### Extensions (default `false`)
-
-| Option              | JS (`camelCase`)       | Rust (`snake_case`)      | Description                                            |
-| ------------------- | ---------------------- | ------------------------ | ------------------------------------------------------ |
-| 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 `#`               |
+| 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
 
@@ -44,7 +58,7 @@ Fast Markdown to HTML/AST parser written in Rust with **zero third-party** parsi
 
 Dangerous URI schemes (`javascript:`, `vbscript:`, `data:` except `data:image/…`) are **always** stripped from link and image destinations, regardless of options.
 
-### Other options
+### Other Options
 
 | Option              | JS (`camelCase`)     | Rust (`snake_case`)   | Default | Description                                       |
 | ------------------- | -------------------- | --------------------- | ------- | ------------------------------------------------- |
@@ -84,6 +98,42 @@ const ast = JSON.parse(astJson);
 
 `parseToAst()` returns a JSON string for portability across JS runtimes and WASM boundaries.
 
+### HTML to Markdown
+
+Convert HTML back to Markdown syntax using `htmlToMarkdown()`. Useful for importing content from HTML sources or round-trip conversion.
+
+```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 } from "ironmark";
+
+const astJson = parseHtmlToAst("<h1>Hello</h1><p>World</p>");
+const ast = JSON.parse(astJson);
+```
+
+### AST to Markdown
+
+Render an AST back to Markdown syntax using `renderMarkdown()`. Combined with `parseToAst()` or `parseHtmlToAst()`, this enables round-trip conversion.
+
+```ts
+import { parseToAst, renderMarkdown } from "ironmark";
+
+const ast = parseToAst("# Hello\n\n**World**");
+const md = renderMarkdown(ast);
+// Returns: "# Hello\n\n**World**"
+```
+
 ### 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.
@@ -264,6 +314,69 @@ Exported AST types:
 - `TableData`
 - `TableAlignment`
 
+### HTML to Markdown
+
+Convert HTML back to Markdown syntax:
+
+```rust
+use ironmark::{html_to_markdown, HtmlParseOptions};
+
+fn main() {
+    let md = html_to_markdown(
+        "<h1>Hello</h1><p><strong>Bold</strong> text</p>",
+        &HtmlParseOptions::default(),
+    );
+    // Returns: "# Hello\n\n**Bold** text"
+}
+```
+
+For AST access, use `parse_html_to_ast()`:
+
+```rust
+use ironmark::{parse_html_to_ast, HtmlParseOptions, UnknownInlineHandling};
+
+fn main() {
+    // Default: strip unknown tags, keep text content
+    let ast = parse_html_to_ast("<p>H<sub>2</sub>O</p>", &HtmlParseOptions::default());
+
+    // Preserve unknown tags as raw HTML
+    let ast = parse_html_to_ast(
+        "<p>H<sub>2</sub>O</p>",
+        &HtmlParseOptions {
+            unknown_inline_handling: UnknownInlineHandling::PreserveAsHtml,
+            ..Default::default()
+        },
+    );
+}
+```
+
+`HtmlParseOptions` fields:
+
+| Field                     | Type                    | Default     | Description                           |
+| ------------------------- | ----------------------- | ----------- | ------------------------------------- |
+| `max_nesting_depth`       | `usize`                 | `128`       | Limit nesting depth (DoS prevention)  |
+| `unknown_inline_handling` | `UnknownInlineHandling` | `StripTags` | How to handle unknown HTML tags       |
+| `max_input_size`          | `usize`                 | `0`         | Truncate input beyond this byte count |
+
+`UnknownInlineHandling` variants:
+
+- `StripTags` — Remove unknown tags, keep text content (default)
+- `PreserveAsHtml` — Keep unknown tags as raw HTML in output
+
+### AST to Markdown
+
+Render an AST back to Markdown syntax:
+
+```rust
+use ironmark::{parse_to_ast, render_markdown, ParseOptions};
+
+fn main() {
+    let ast = parse_to_ast("# Hello\n\n**World**", &ParseOptions::default());
+    let md = render_markdown(&ast);
+    // Returns: "# Hello\n\n**World**"
+}
+```
+
 ### 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ironmark",
-  "version": "1.11.4",
+  "version": "1.12.1",
   "description": "Very fast markdown parser in Rust, consumable from JavaScript/TypeScript via WebAssembly",
   "keywords": [
     "markdown",

package/wasm/index.d.ts

@@ -118,3 +118,69 @@ export declare function renderAnsi(
   options?: ParseOptions,
   ansiOptions?: AnsiOptions,
 ): string;
+
+/**
+ * Options for HTML-to-Markdown parsing.
+ */
+export interface HtmlParseOptions {
+  /**
+   * If true, unknown HTML tags (like `<sup>`, `<sub>`, `<abbr>`) are preserved
+   * as raw HTML in the Markdown output. If false (default), unknown tags are
+   * stripped but their text content is kept.
+   */
+  preserveUnknownAsHtml?: boolean;
+}
+
+/**
+ * Parse an HTML string and return the AST as a JSON string.
+ *
+ * This converts HTML back into the same AST structure used by the Markdown parser,
+ * enabling HTML-to-Markdown conversion.
+ *
+ * @param html - HTML source string.
+ * @param preserveUnknownAsHtml - If true, unknown HTML tags are preserved as raw HTML.
+ * @returns JSON string representing the AST.
+ *
+ * @example
+ * ```ts
+ * import { parseHtmlToAst } from "ironmark";
+ * const ast = parseHtmlToAst("<h1>Hello</h1><p>World</p>");
+ * console.log(JSON.parse(ast));
+ * ```
+ */
+export declare function parseHtmlToAst(html: string, preserveUnknownAsHtml?: boolean): string;
+
+/**
+ * Convert HTML to Markdown.
+ *
+ * This parses HTML and renders it as Markdown syntax.
+ *
+ * @param html - HTML source string.
+ * @param preserveUnknownAsHtml - If true, unknown HTML tags are preserved as raw HTML in output.
+ * @returns Markdown string.
+ *
+ * @example
+ * ```ts
+ * import { htmlToMarkdown } from "ironmark";
+ * const md = htmlToMarkdown("<p><strong>Bold</strong> text</p>");
+ * // Returns: "**Bold** text"
+ * ```
+ */
+export declare function htmlToMarkdown(html: string, preserveUnknownAsHtml?: boolean): string;
+
+/**
+ * Render an AST (as JSON) to Markdown.
+ *
+ * This takes a JSON string representing an ironmark AST and renders it as Markdown.
+ *
+ * @param astJson - JSON string representing the AST (as returned by `parseToAst` or `parseHtmlToAst`).
+ * @returns Markdown string.
+ *
+ * @example
+ * ```ts
+ * import { parseToAst, renderMarkdown } from "ironmark";
+ * const ast = parseToAst("# Hello\n\n**World**");
+ * const md = renderMarkdown(ast);
+ * ```
+ */
+export declare function renderMarkdown(astJson: string): string;