`) ([#772](https://github.com/xberg-io/html-to-markdown/issues/772)).
* Markdown and Djot output write one space between the text of a `
` and a word or a button right beside it when the source has no white space between them, as plain text output does. `All Methods Instance Methods
` gave `All MethodsInstance Methods`. Where the source has white space, the output is the same.
* An inline `` keeps its text and no longer adds the words `SVG Image`. Its text is its `aria-label`, the `` and `<desc>` of the graphic, its `<text>` elements and the HTML in a `<foreignObject>`, in document order. Style sheets, scripts, metadata and the content of `<defs>` and `<symbol>` are not text, and a `<use>` reference is not followed. A `<switch>` gives the child that a reader of English gets. An element with `display="none"` or `visibility="hidden"` gives nothing, as hidden text outside a graphic gives nothing. `aria-hidden="true"` removes the label, the title and the description. That text is the alt text of the image, and it is what `inline_data_media = alt_text_only`, a heading and plain text output write, with the escaping of any other text. A graphic with no text writes nothing there, and an image with an empty alt text when the payload is kept. An icon link no longer takes the style sheet of its graphic as its label ([#750](https://github.com/xberg-io/html-to-markdown/issues/750)).
* A graphic in a heading is written as its text also with `extract_metadata = false` and `highlight_style = none`. With those options it was written as a `data:` image, because the fast converter has no rule for a heading. It now leaves a page with a graphic in a heading, with a hidden element in a graphic, or with a link that has a name and no text, to the full converter ([#766](https://github.com/xberg-io/html-to-markdown/issues/766)).
* Two page shapes no longer take quadratic time in the pass that removes hidden elements: many tag starts with no end (`<a` and a space, repeated), and many attribute values with no closing quote (`<g a="` repeated). A 120 KB page with 40,000 such tag starts in a graphic took 16 seconds; 200,000 of them now take 20 milliseconds. The pass reads each tag once. A `<` inside a tag is part of an attribute value there, so an attribute value that holds markup is no longer cut. Other page shapes are still slow ([#765](https://github.com/xberg-io/html-to-markdown/issues/765)).
* Text that is only white space no longer makes the conversion fail when `include_document_structure` is on, and `build_document_structure` no longer panics on it. The Markdown is the same as with the structure off. Neither builder records an empty heading, paragraph or list item ([#749](https://github.com/xberg-io/html-to-markdown/issues/749)).
* A code block inside a list item keeps the indentation of every line. A line after a blank line got four spaces for each list level in place of its own indentation, so `<ol><li><p>Save this:</p><pre>def f(x):\n if x:\n\n return 1\n</pre></li></ol>` wrote `return 1` at the level of `if x:`. It now writes it eight spaces in, as in the page ([#769](https://github.com/xberg-io/html-to-markdown/issues/769)).
* A code block whose lines are separate block elements has one line for each. A `div`, `section` or other plain container inside a `pre` starts a line and ends a line, as in a browser, and adds no blank line: `<pre><div>a<br></div><div>b<br></div></pre>` wrote `a`, a blank line, `b` and now writes `a`, `b`. An empty container is no line. A line feed between two containers is still a blank line, because a browser shows one ([#770](https://github.com/xberg-io/html-to-markdown/issues/770)).
* Two or more blank lines in a row inside a fenced code block stay, and so do the spaces at the end of a line of code: `<pre>import a\n\n\nclass B:\n</pre>` wrote one blank line and now writes two. The rules that fold blank lines and trim line ends still apply to the text outside of code ([#783](https://github.com/xberg-io/html-to-markdown/issues/783)).
* With `code_block_style = indented`, a code block that starts a block quote keeps the four spaces of its first line. Without them a Markdown reader takes the code for a paragraph: `<blockquote><pre>a\nb\n</pre></blockquote>` wrote `> a`, `> b` and now writes `> a`, `> b`. With that style the blank lines and the spaces at the end of a line of code also stay, at the top level, in a block quote and in a list item: `<pre>a \n\n\nb\n</pre>` wrote `" a \n\n b"` and now writes `" a \n\n\n b"` ([#799](https://github.com/xberg-io/html-to-markdown/issues/799)).
* With `code_block_style = indented`, a code block that starts the description of a definition list keeps the four spaces of its first line, and a blank line goes between the term and the code: the full converter wrote `"t\na\n b"` for `<dl><dt>t</dt><dd><pre>a\nb\n</pre></dd></dl>`, and the full and fast converters now write `"t\n\n a\n b"`. The spaces at the end of the last line of that code stay too ([#799](https://github.com/xberg-io/html-to-markdown/issues/799)).
* Add `expand_abbreviations` and `include_blockquote_citations` options, enabled by default.
* Keep one blank quote line between lists and blocks, preserving blank lines inside code.
* Convert repeated unfinished tags, unclosed hidden elements, and inline list fragments with linear scans.
* Repair a page that ends a paragraph again after the end tag of its parent, or whose head has no end tag, from the first parse with no second tokenizer pass; at 512 levels the repair stops and the input after that point is converted as written, past the node budget of the repair the whole page is converted as written, each with a `malformed_html` warning.
* A line break in the source before an inline element is one space between two words, in every container. Before, the words on the two sides of a `<span>` were joined, with an empty span and with a span that holds text. This changes the default output: `<p>hard to read\n<span id="index-0"></span>docstrings</p>` gave `hard to readdocstrings` and gives `hard to read docstrings`, `<p>one\n<span>two</span> three</p>` gave `onetwo three` and gives `one two three`, and `<ul><li>one\n<span id="a"></span>two</li></ul>` gave `- onetwo` and gives `- one two`. Outside a paragraph the line break before any other inline element was a line break, and it is a space now, as a browser shows it: `<div>one\n<b>y</b></div>` gave `one` and `**y**` on two lines and gives `one **y**`. A line break before a block stays a line break, and so does a line break before an inline element whose content starts with a block ([#778](https://github.com/xberg-io/html-to-markdown/issues/778)).
* White space on the two sides of the start of an inline element is one space, and it goes outside the marks of the element: `<p>one <b> y</b>two</p>` gave `one **y**two` with two spaces and gives `one **y**two`. The same holds for `<kbd>`, `<samp>`, `<abbr>`, `<dfn>`, `<del>`, `<ins>`, `<mark>`, `<sub>` and `<sup>`. At the start of a line such an element starts with no space: `<div>a<br><sup> x</sup></div>` gave a space and `x` on the second line and gives `x`.
* A line break is no space when an element or a comment stands between it and a zero-width space, as in a browser: the zero-width space is a place where a line can break, so the two parts are one word. `<p>one \n <span></span>two</p>` gave `one`, a space, the zero-width space and `two`, and gives `one`, the zero-width space and `two`. The line break can be the last content of an element that only wraps text: `<p><span>one\n</span>two</p>` gave `one`, a space, the zero-width space and `two`, and gives `one`, the zero-width space and `two`. Two or more line breaks are one line break there: `<p>one\n\n<span></span>two</p>` gave two paragraphs and gives one word. A space that is not a line break stays. The converter keeps the space before a zero-width space only when the `style` attribute of the element between them, or of an element around them, sets `display` or `white-space`: `<p>one\n<span style="display:inline-block"></span>two</p>` keeps the space, and `<p>one\n<span style="color:red"></span>two</p>` gives one word. A line break directly before the zero-width space in the same text is not changed: `<p>one\ntwo</p>` keeps its line break.
* A `<footer>`, a `<section>`, an `<article>`, an `<aside>`, a `<header>` and a `<main>` start with no space. White space at the start of a block is no space, and the full converter wrote one there. This changes the default output: `x<footer> Logo</footer>` gave `x` and then `Logo` with a space at the start of its line, and gives `x` and then `Logo` with none. The same holds for an inline element at the start: `x<footer><b> Logo</b></footer>` gave a space and `**Logo**` and gives `**Logo**`.
* The strict white space mode writes what it wrote before these changes.
* The white space after an image, an inline graphic, a video or a form control at the start of a document is kept. This changes the default output: `<p><img src="/i.png" alt="alt"> text</p>` gave `text` and gives ` text`, and `<p><a href="/x"><img src="/i.png" alt="alt"> text</a></p>` gave `[text](/x)` and gives `[ text](/x)`. With no white space in the source the output has none ([#762](https://github.com/xberg-io/html-to-markdown/issues/762)).
* Blocks inside a link label or a heading are separate words at every depth of nesting. This changes the default output: `<a href="/x"><div><div>Next</div><div>Cross-references</div></div></a>` gave `[NextCross-references](/x)` and gives `[Next Cross-references](/x)`, and `<h2><p>a</p><p>b</p></h2>` gave `## ab` and gives `## a b`. Inline content beside a block in a link no longer gets a space that the source does not have: `<a href="/x"><b>H</b>ello<div>x</div></a>` gave `[**H** ello x](/x)` and gives `[**H**ello x](/x)`. The text of an image stays a word of its own there: `<a href="/x"><img src="/i.png" alt="Logo"><span>Docs</span><p>desc</p></a>` gives `[Logo Docs desc](/x)`, as before ([#751](https://github.com/xberg-io/html-to-markdown/issues/751)).
* An inline element that holds only a tab is one space: `<p>one<span>\t</span>two</p>` gave `one`, a tab and `two`, and gives `one two`.
* White space on the two sides of an element that writes nothing is one space, also in a table cell: `<p>one <span id="a"></span> two</p>` gave `one two` with two spaces and gives `one two`, and `<p><span>one </span> two</p>` does the same. The rule holds for every element that writes nothing: an image that `inline_data_media: DropElement` removes, a link with no name, an element that a visitor skips. With `DropElement`, `<p>Before <img src="data:image/png;base64,AAAA" alt="icon"> after</p>` gave `Before after` and gives `Before after`.
* A no-break space in an element of its own is kept after a space: `<p>one <span> </span> two</p>` gave `one two` and gives `one`, a space, the no-break space, a space and `two`. A no-break space in running text is written as a space, as before. In a link label a no-break space beside a space is one space on both converters.
* A no-break space that starts a text is kept after a space when an element with no text stands between the two: `<p>a <span></span> b</p>` and `<p>a <img> b</p>` give `a`, two spaces and `b`, as a browser shows them. ` `, ` `, ` ` and the character do the same. An element that holds only white space has no text: `<p>a <span> </span> b</p>` gives the same. After a `span` whose text ends with a space the no-break space is kept too: `<p>a <span>x </span> b</p>` gives `a x`, two spaces and `b`. A line end before an empty `span` and the no-break space after it are one space. After a `<br>` in a heading and at the start of an element the no-break space is still the one space. After a `<br>` in a table cell the no-break space is kept, also in a heading in the cell: `<td>a<br> b</td>` gives `a`, two spaces and `b`, as before. Inside one text, and with only a comment between the two, a space and a no-break space are one space, as before.
* Plain text output writes each term and each description of a definition list as a block of its own, as Markdown output does. Before, the words joined: `<dl><dt>Bread</dt><dd>Baked dough.</dd></dl>` gave `BreadBaked dough.`. A `<dt>` or a `<dd>` outside a `<dl>` is a block too.
* Plain text output writes the caption of a table as a block of its own before the rows. Before, the caption text was lost, and a table with only a caption wrote nothing. A caption that `exclude_selectors` names is not written.
* A visitor sees a form inside a heading again, as in 3.17.2. Before, the form text stayed in the heading and the visitor was not called. With no visitor the output is the same as before ([#906](https://github.com/xberg-io/html-to-markdown/issues/906)).
## \[3.17.2] - 2026-10-06
[Section titled “\[3.17.2\] - 2026-10-06”](#3172---2026-10-06)
### Changed
[Section titled “Changed”](#changed-1)
* Rust dependencies and all generated bindings, documentation, test applications and E2E suites were refreshed with Alef 0.105.0.
### Fixed
[Section titled “Fixed”](#fixed-1)
* HTML highlight output now preserves leading and trailing whitespace inside `<mark>` boundaries ([#744](https://github.com/xberg-io/html-to-markdown/issues/744)).
* Whitespace between adjacent inline images is preserved instead of joining their Markdown output ([#746](https://github.com/xberg-io/html-to-markdown/issues/746)).
* Blank lines in image alternative text are encoded without losing line feeds or producing invalid Markdown image labels ([#747](https://github.com/xberg-io/html-to-markdown/issues/747)).
## \[3.17.1] - 2026-10-05
[Section titled “\[3.17.1\] - 2026-10-05”](#3171---2026-10-05)
### Fixed
[Section titled “Fixed”](#fixed-2)
* Caller-provided `base_url` values now resolve relative URLs without being emitted as document `base` metadata when the source has no `<base href>` ([#743](https://github.com/xberg-io/html-to-markdown/issues/743)).
## \[3.17.0] - 2026-10-04
[Section titled “\[3.17.0\] - 2026-10-04”](#3170---2026-10-04)
### Added
[Section titled “Added”](#added-1)
* Structure extraction now records inline annotations during the conversion traversal, including links and inline formatting, while preserving visitor, exclusion and depth semantics ([#741](https://github.com/xberg-io/html-to-markdown/issues/741)).
* The WASM converter now rejects inputs above a configurable 2 MiB default limit with a typed error, preventing unexpectedly large allocations in browser and edge runtimes ([#508](https://github.com/xberg-io/html-to-markdown/issues/508)).
### Changed
[Section titled “Changed”](#changed-2)
* WASM class-valued getters and setters now use explicit detached-copy semantics; callers reassign modified values rather than mutating an ineffective borrowed wrapper ([#729](https://github.com/xberg-io/html-to-markdown/issues/729)).
* Conversion reuses validated parser state and precomputed sibling context, and raw-text stripping uses byte-search skipping, reducing repeated DOM and scan work without changing output ([#649](https://github.com/xberg-io/html-to-markdown/issues/649), [#715](https://github.com/xberg-io/html-to-markdown/issues/715)).
* Rust and polyglot dependencies, supported toolchains and generated bindings were refreshed; Alef is pinned to 0.103.14.
* CI now uses baseline-free quality gates, stricter delegated-workflow checks and reliable benchmark timing and regression thresholds ([#736](https://github.com/xberg-io/html-to-markdown/issues/736), [#738](https://github.com/xberg-io/html-to-markdown/issues/738)).
### Fixed
[Section titled “Fixed”](#fixed-3)
* Lists, task items, block quotes and wrapped output now preserve markers, indentation, hard breaks and block boundaries across nested and inline containers ([#594](https://github.com/xberg-io/html-to-markdown/issues/594), [#603](https://github.com/xberg-io/html-to-markdown/issues/603), [#604](https://github.com/xberg-io/html-to-markdown/issues/604), [#607](https://github.com/xberg-io/html-to-markdown/issues/607), [#611](https://github.com/xberg-io/html-to-markdown/issues/611), [#612](https://github.com/xberg-io/html-to-markdown/issues/612), [#613](https://github.com/xberg-io/html-to-markdown/issues/613), [#614](https://github.com/xberg-io/html-to-markdown/issues/614), [#615](https://github.com/xberg-io/html-to-markdown/issues/615), [#616](https://github.com/xberg-io/html-to-markdown/issues/616), [#617](https://github.com/xberg-io/html-to-markdown/issues/617), [#619](https://github.com/xberg-io/html-to-markdown/issues/619), [#620](https://github.com/xberg-io/html-to-markdown/issues/620), [#622](https://github.com/xberg-io/html-to-markdown/issues/622), [#623](https://github.com/xberg-io/html-to-markdown/issues/623), [#625](https://github.com/xberg-io/html-to-markdown/issues/625), [#626](https://github.com/xberg-io/html-to-markdown/issues/626), [#627](https://github.com/xberg-io/html-to-markdown/issues/627), [#629](https://github.com/xberg-io/html-to-markdown/issues/629), [#630](https://github.com/xberg-io/html-to-markdown/issues/630), [#631](https://github.com/xberg-io/html-to-markdown/issues/631), [#633](https://github.com/xberg-io/html-to-markdown/issues/633), [#634](https://github.com/xberg-io/html-to-markdown/issues/634), [#635](https://github.com/xberg-io/html-to-markdown/issues/635), [#636](https://github.com/xberg-io/html-to-markdown/issues/636), [#637](https://github.com/xberg-io/html-to-markdown/issues/637), [#643](https://github.com/xberg-io/html-to-markdown/issues/643), [#650](https://github.com/xberg-io/html-to-markdown/issues/650), [#651](https://github.com/xberg-io/html-to-markdown/issues/651), [#653](https://github.com/xberg-io/html-to-markdown/issues/653), [#654](https://github.com/xberg-io/html-to-markdown/issues/654), [#655](https://github.com/xberg-io/html-to-markdown/issues/655), [#657](https://github.com/xberg-io/html-to-markdown/issues/657), [#658](https://github.com/xberg-io/html-to-markdown/issues/658), [#659](https://github.com/xberg-io/html-to-markdown/issues/659), [#662](https://github.com/xberg-io/html-to-markdown/issues/662), [#668](https://github.com/xberg-io/html-to-markdown/issues/668), [#669](https://github.com/xberg-io/html-to-markdown/issues/669), [#674](https://github.com/xberg-io/html-to-markdown/issues/674), [#675](https://github.com/xberg-io/html-to-markdown/issues/675), [#678](https://github.com/xberg-io/html-to-markdown/issues/678), [#680](https://github.com/xberg-io/html-to-markdown/issues/680), [#681](https://github.com/xberg-io/html-to-markdown/issues/681), [#686](https://github.com/xberg-io/html-to-markdown/issues/686), [#734](https://github.com/xberg-io/html-to-markdown/issues/734)).
* Markdown and Djot escaping now keeps literal markers, rule-like text, table delimiters, code-span backticks and hard breaks valid in their surrounding container ([#624](https://github.com/xberg-io/html-to-markdown/issues/624), [#638](https://github.com/xberg-io/html-to-markdown/issues/638), [#661](https://github.com/xberg-io/html-to-markdown/issues/661), [#688](https://github.com/xberg-io/html-to-markdown/issues/688), [#689](https://github.com/xberg-io/html-to-markdown/issues/689), [#697](https://github.com/xberg-io/html-to-markdown/issues/697), [#705](https://github.com/xberg-io/html-to-markdown/issues/705), [#706](https://github.com/xberg-io/html-to-markdown/issues/706), [#707](https://github.com/xberg-io/html-to-markdown/issues/707), [#708](https://github.com/xberg-io/html-to-markdown/issues/708), [#709](https://github.com/xberg-io/html-to-markdown/issues/709), [#710](https://github.com/xberg-io/html-to-markdown/issues/710), [#713](https://github.com/xberg-io/html-to-markdown/issues/713), [#735](https://github.com/xberg-io/html-to-markdown/issues/735)).
* Tables and headings now retain surrounding text, block boundaries, checkboxes and nested content consistently between the full and fast converters ([#628](https://github.com/xberg-io/html-to-markdown/issues/628), [#645](https://github.com/xberg-io/html-to-markdown/issues/645), [#646](https://github.com/xberg-io/html-to-markdown/issues/646), [#647](https://github.com/xberg-io/html-to-markdown/issues/647), [#679](https://github.com/xberg-io/html-to-markdown/issues/679), [#692](https://github.com/xberg-io/html-to-markdown/issues/692), [#702](https://github.com/xberg-io/html-to-markdown/issues/702), [#722](https://github.com/xberg-io/html-to-markdown/issues/722), [#723](https://github.com/xberg-io/html-to-markdown/issues/723), [#724](https://github.com/xberg-io/html-to-markdown/issues/724), [#725](https://github.com/xberg-io/html-to-markdown/issues/725), [#730](https://github.com/xberg-io/html-to-markdown/issues/730), [#732](https://github.com/xberg-io/html-to-markdown/issues/732)).
* Hard line breaks now remain in place across source whitespace, inline buffers, links and both Markdown and Djot output ([#690](https://github.com/xberg-io/html-to-markdown/issues/690), [#691](https://github.com/xberg-io/html-to-markdown/issues/691), [#693](https://github.com/xberg-io/html-to-markdown/issues/693), [#696](https://github.com/xberg-io/html-to-markdown/issues/696), [#698](https://github.com/xberg-io/html-to-markdown/issues/698), [#704](https://github.com/xberg-io/html-to-markdown/issues/704), [#711](https://github.com/xberg-io/html-to-markdown/issues/711), [#718](https://github.com/xberg-io/html-to-markdown/issues/718)).
* Metadata, preprocessing and URL handling now preserve effective base URLs and titles, remove page headers as configured, and ignore link-like text inside raw-text elements ([#608](https://github.com/xberg-io/html-to-markdown/issues/608), [#716](https://github.com/xberg-io/html-to-markdown/issues/716), [#719](https://github.com/xberg-io/html-to-markdown/issues/719), [#739](https://github.com/xberg-io/html-to-markdown/issues/739), [#740](https://github.com/xberg-io/html-to-markdown/issues/740)).
* The fast converter builds cleanly without default features, and generated R reference pages now match the public API ([#593](https://github.com/xberg-io/html-to-markdown/issues/593), [#596](https://github.com/xberg-io/html-to-markdown/issues/596)).
## Archives
[Section titled “Archives”](#archives)
* [3.16.0 through 3.14.0](changelog-archive-6.md)
* [3.13.0 through 3.11.5](changelog-archive-1.md)
* [3.11.4 through 3.6.21](changelog-archive-2.md)
* [3.6.20 through 3.2.0](changelog-archive-3.md)
* [3.1.0 through 2.14.1](changelog-archive-4.md)
* [2.14.0 through 1.x](changelog-archive-5.md)
# Changelog archive: 3.13.0–3.11.5
## \[3.13.0] - 2026-09-14
[Section titled “\[3.13.0\] - 2026-09-14”](#3130---2026-09-14)
### Changed
[Section titled “Changed”](#changed)
* **BREAKING (java): enum constants are now `SCREAMING_SNAKE_CASE`.** `LinkStyle.Inline` becomes `LinkStyle.INLINE`, `HeadingStyle.Atx` becomes `HeadingStyle.ATX`, and so on across every generated enum; builder default sites move with them. The JSON wire values are unchanged, so no serialized payload moves – only the Java-facing constant names.
* **BREAKING: the `RDFa` structured-data variant is spelled consistently across bindings.** One Rust variant previously generated seven different names. Each binding now uses the correct acronym segmentation for its own convention: `rdfa` (python `options.py`, elixir, ruby, swift), `RDFA` (python stub, java, kotlin), `Rdfa` (csharp, go). Dart keeps `rdFa`, which is what flutter_rust_bridge itself declares. The wire value `"rdfa"` is unchanged everywhere.
* **BREAKING (python): the type stub declared an enum member the runtime does not have.** The `.pyi` emitted `StructuredDataType.RD_FA` while the extension declares `RDFA`, so a type checker accepted the name that raises `AttributeError` and rejected the one that works. Both now agree on `RDFA`.
* **BREAKING (elixir): `VisitResult`’s payload key matches the NIF struct.** `%{type: :custom, value: ...}` becomes `%{type: :custom, custom: ...}`, and `:error` likewise. The NIF struct has always declared `custom`/`error` fields, so the previous shape never round-tripped.
* **BREAKING (ruby): `VisitResult.from_hash` reads the real wire key.** It read `_0`; the core enum is adjacently tagged with `content = "output"`, so `_0` never matched and the payload was silently discarded in both directions.
### Fixed
[Section titled “Fixed”](#fixed)
* **`<br>` inside an inline code span no longer emits a raw newline inside the backticks** ([#487](https://github.com/xberg-io/html-to-markdown/issues/487)). `<code>A<br>B</code>` produced `` `A\nB` ``, which `CommonMark` does not read back as one code span. The span is now split and joined by a real hard break – `` `A` `` + the `newline_style` marker + `` `B` `` – so the marker sits outside the span, where it is syntax rather than content, and `<code>` behaves like `<b>` and `<i>`, which already emitted hard breaks here. The output is round-trip stable through a `CommonMark` render; the previous form was not. `<kbd>` and `<samp>` had the same defect and are fixed with it.
Both tiers were wrong and disagreed with each other – Tier 1 emitted `` `A \nB` ``, leaking the two-space marker into the code content – and both are fixed, so the tiers now agree. A pre-existing Tier-1 bug surfaced on the way: inside a link label the `<br>` branch ran before the code-span check, trapping two spaces in the first segment.
Contexts that cannot carry a hard break fold to a single space instead of splitting: headings and table cells. A link label splits, matching what a bare `<br>` in link text already did.
* **A literal line ending inside an inline code span folds to a space.** `<code>a\nb</code>` (a real newline in the source, no `<br>`) produced `` `a\nb` ``. `CommonMark` gives a line ending inside a code span no hard-break meaning and renders it as a space, so the old output was never round-trip stable. `<pre>` and fenced blocks are unaffected and keep every newline.
### Note
[Section titled “Note”](#note)
`html5ever` stays pinned at 0.39.0. 0.40.0’s serializer drops the `C2` lead byte for every codepoint in U+0080-U+00BF except NBSP (`§`, `©`, `°`, `±`, `»`, …), emitting invalid UTF-8. In this crate that makes `repair_with_html5ever` fail its `from_utf8` check and silently skip the repair pass on any document containing one of those characters – it fails safe, but degrades quality invisibly. Fixed upstream in servo/html5ever#784, which is merged but not yet published; this crate will adopt 0.40.x once it is.
## \[3.12.4] - 2026-09-12
[Section titled “\[3.12.4\] - 2026-09-12”](#3124---2026-09-12)
### Fixed
[Section titled “Fixed”](#fixed-1)
* Render `<strike>` as strikethrough. The Tier-2 inline dispatch listed only `del`/`s`, so `<strike>` fell through to a plain child walk and lost its `~~` markers entirely.
* Merge adjacent inline elements that share a repeated-character delimiter, extending the [#483](https://github.com/xberg-io/html-to-markdown/issues/483) fix from `<em>`/`<strong>` to every other family. `<del>A</del><del>B</del>` produced `~~A~~~~B~~`, which CommonMark reparses as one strikethrough containing `A~~~~B`; two adjacent code spans produced `` `A ``B` ``, reparsed as one span carrying the literal backticks. ``, `*`, ```and` had the same defect.``*
* Keep the word separator a whitespace-only inline element stands for, extending the [#481](https://github.com/xberg-io/html-to-markdown/issues/481) fix to `<ins>`, `<sub>`, `<sup>`, `<var>`, `<dfn>`, `<abbr>` and `<q>`, each of which joined the words either side.
* Keep `<code> </code>` as a code span whose content is a space. It was dropped outright, and the delimiter-space padding that an all-spaces body used to get turned one space into three (CommonMark strips one space per end only when the content is not entirely spaces).
* Stop `<ins>`, `<kbd>`, `<samp>`, `<var>` and `<dfn>` from emitting their markers inside a code span or fenced block, where `==`, a second backtick pair and `*` are literal content rather than formatting. Every other inline handler already suppressed itself there.
* Close 22 Tier-1/Tier-2 output divergences across the inline elements, found by sweeping both converters over 26 tags. Tier-1 now reproduces `<var>`/`<dfn>`, bails on the shapes it cannot (`<q>`, `<mark>`, the new delimiter merges, a whitespace-only body), and suppresses `<strong>`/`<em>` markers inside a code span as Tier-2 does.
* Treat adjacent duplicate Rust warning flags as equivalent in benchmark provenance checks while preserving timing gates.
* Publish every native NuGet runtime package required by the managed package’s runtime graph.
* Upload Dart native archives and checksums required by the generated package downloader.
* Publish Go installer archive aliases and required SHA-256 sidecars.
* Verify the installed Homebrew CLI and FFI versions directly in the registry smoke task.
* Stage original native archives through the shared Zig packager; the 3.12.3 source archive requires separate C FFI libraries.
* Merge adjacent inline emphasis into a single delimiter run, so `<i>A</i><i>B</i><i>C</i>` renders as `*ABC*` rather than the `*A**B**C*` CommonMark reparses as nested emphasis ([#483](https://github.com/xberg-io/html-to-markdown/issues/483)).
* Emit exactly one space for a whitespace-only inline element; `A<i> </i>B` duplicated it and, inside a paragraph, `<p>A<i> </i>B</p>` dropped it entirely ([#481](https://github.com/xberg-io/html-to-markdown/issues/481)).
* Drive the musl Node cross-compile through the shared build action, whose per-leg artifact staging replaces the `napi artifacts` call that `@napi-rs/cli` 3.9.1 made fail on any single-target matrix leg.
* Keep the visible text of a `<tr>` nested directly inside a `<td>`, a shape malformed newsletter HTML produces; the row and its content were dropped silently. The same fix repairs tbody-less tables with implicitly-closed cells, where `<table><tr><th>h1<th>h2<tr><td>a<td>b</table>` emitted only a one-column header and dropped both the second header and the entire data row ([#486](https://github.com/xberg-io/html-to-markdown/issues/486)).
* Render a data table’s nested single-cell table as its own table instead of flattening it into a cell of escaped pipes ([#484](https://github.com/xberg-io/html-to-markdown/issues/484)).
* Apply the WHATWG numeric character reference replacement table, so `›` decodes to `›` rather than a raw C1 control character; null, surrogate and out-of-range references now yield U+FFFD ([#485](https://github.com/xberg-io/html-to-markdown/issues/485)).
## \[3.12.3] - 2026-09-09
[Section titled “\[3.12.3\] - 2026-09-09”](#3123---2026-09-09)
### Fixed
[Section titled “Fixed”](#fixed-2)
* Preserve visible images inside `font-size: 0` wrappers ([#476](https://github.com/xberg-io/html-to-markdown/issues/476)).
* Recover table cells following malformed Office namespace tags ([#477](https://github.com/xberg-io/html-to-markdown/issues/477)).
* Render data tables inside one-cell layout wrappers as separate Markdown tables ([#478](https://github.com/xberg-io/html-to-markdown/issues/478)).
* Repair nested anchors so both link destinations remain clickable ([#479](https://github.com/xberg-io/html-to-markdown/issues/479)).
* Resolve unpublished native Node packages from the workspace during frozen documentation installs.
* Build prerelease PHP extensions against the local Rust core and committed dependency lockfile.
* Preserve native error codes on typed C# conversion exceptions.
* Prevent panics when nested list visitors shorten earlier output or replace it with multibyte text ([#474](https://github.com/xberg-io/html-to-markdown/issues/474)).
* Generate R and Ruby bindings that pass strict Clippy checks while preserving visitor and conversion behavior.
* Accept explicit `nil` for optional Ruby conversion fields.
* Use canonical URL-escape enum values in fixtures so Node and WebAssembly suites regenerate completely.
* Point Ruby dependency-update tasks at the native crate and remove the obsolete duplicate Rust workspace.
### Changed
[Section titled “Changed”](#changed-1)
* Refactor MCP helpers, image construction, and visitor state to remove three lint suppressions while preserving preprocessing validation order ([#466](https://github.com/xberg-io/html-to-markdown/pull/466)).
* Regenerate all bindings, end-to-end suites, and snippets with Alef 0.85.11.
* Refresh dependency lockfiles across Rust workspaces.
## \[3.12.2] - 2026-09-07
[Section titled “\[3.12.2\] - 2026-09-07”](#3122---2026-09-07)
### Fixed
[Section titled “Fixed”](#fixed-3)
* **`bullets` now applies to layout-table rows** ([#472](https://github.com/xberg-io/html-to-markdown/issues/472)). A table with inconsistent column counts and no `<th>`/`<caption>` is treated as a layout table and renders each row as a list item — but that renderer hardcoded `-` and never read `options.bullets`, so configuring the option had no effect on the markers actually emitted. Surfaced by the reporter of #470, who set `bullets` to `"*+-"` in 3.12.0 and still got hyphens.
The marker now cycles through `bullets` by nesting depth the same way list items do, so a layout table nested inside a list takes the next marker rather than repeating its parent’s. The prefix strip that prevents a doubled-up marker assumed a hyphen as well, and now accepts any configured bullet.
Default output is unchanged — the default `bullets` string already starts with `-`. Tier-1 bails on layout tables, so this is a Tier-2 path with no parity mirror.
## \[3.12.1] - 2026-09-07
[Section titled “\[3.12.1\] - 2026-09-07”](#3121---2026-09-07)
Correctness release covering the four defects reported against 3.12.0. Three are conversion bugs in the core, one extends the hidden-element rule; all four were reported through the Java binding and reproduce identically in every language.
### Fixed
[Section titled “Fixed”](#fixed-4)
* **An uppercase void element no longer swallows the rest of the document** ([#467](https://github.com/xberg-io/html-to-markdown/issues/467)). The bundled `astral-tl` parser matches void elements against an all-lowercase table using a tag’s raw source bytes, so `<META>` missed it and was pushed onto the open-element stack as a *container*: the parent’s close tag could not pop it and every following sibling was absorbed as its child. For `<head><META ...></head><body>` that left `<body>` a grandchild of `<head>`, out of reach of the direct-child rescue in `handle_head`, and the whole document converted to an empty string. The `charset` attribute in the report was incidental – the crate has no charset handling, and every HTML5 void element (`<BR>`, `<IMG>`, `<HR>`, `<INPUT>`, `<LINK>`, …) reproduced it. Tier-2 now lowercases void-element tag *names* during preprocessing; attribute names and values are left byte for byte alone. Tier-1 already lowercased before lookup, so this also closes a tier divergence.
* **A nested table inside a cell keeps its row boundaries under `br_in_tables`** ([#469](https://github.com/xberg-io/html-to-markdown/issues/469)). A Markdown cell cannot hold a nested table, so the inner table is flattened into the outer cell with its pipes escaped. Until 3.11.2, `br_in_tables: true` merely skipped the whole-cell newline fold, letting the inner rows leak out of the cell as raw newlines – malformed, but a GFM parser could still see two rows. Making that fold unconditional (correctly, for issues #456 and #457: a raw newline between two pipes splits the row across physical lines) collapsed the rows onto one line joined by spaces and erased the boundaries. The fold stays unconditional; the flattened rows are now joined with the literal `<br>` that `br_in_tables` already means everywhere else in a cell. A preceding sibling is separated from the nested table too, which previously ran straight into its first pipe (`Before\| ID`). **This restores row boundaries, not table structure** – a real nested GFM table remains impossible and the inner pipes stay escaped.
* **Adjacent paragraphs in a layout-table cell are separated** ([#470](https://github.com/xberg-io/html-to-markdown/issues/470)). A table with inconsistent column counts and no `<th>`/`<caption>` renders each row as a list item, and those cells convert as inline. That suppressed the ordinary block separator while never reaching the table-cell continuation rule, so `<p><b>Alice Example</b></p><p><i>Customer Service</i></p>` emitted `**Alice Example***Customer Service*` – merged words and invalid emphasis. Such cells now follow the settled cell rule from issues #453/#454: a literal `<br>` under `br_in_tables`, a single space otherwise. `<div>` continuations are covered by the same change. Layout rows are list items, so they still do not take table-cell pipe or emphasis escaping. Not a regression – this predates 3.8.3.
### Changed
[Section titled “Changed”](#changed-2)
* **`font-size: 0` now marks an element as not rendered** ([#468](https://github.com/xberg-io/html-to-markdown/issues/468)), joining `display: none`, `visibility: hidden` and the `hidden` attribute. Reported against generated email banners whose marker text reached the Markdown despite being invisible in a browser. Any exact zero length is recognised (`0`, `0px`, `0.0em`, `.0%`, in any casing, with or without `!important`) and the CSS last-declaration-wins cascade applies as it already does to `display`.
**This drops content that previous versions emitted.** One case is deliberately exempt: the same declaration is the classic inline-block/email spacing hack, where the wrapper kills inter-child whitespace and each child restores a readable size. When a descendant re-declares a non-zero `font-size`, the subtree is kept. That guard is a one-level-of-inheritance heuristic, not a cascade – a size restored from a stylesheet is out of reach of a byte-level pass. Tier-1 has no subtree awareness and bails on any `font-size: 0`, deferring to the tier that can see the descendant.
Detection remains unconditional, as it has always been for the other three: no option governs it.
## \[3.12.0] - 2026-08-31
[Section titled “\[3.12.0\] - 2026-08-31”](#3120---2026-08-31)
Correctness release. A broad pass over converter correctness: defects in the shipped output, plus a run of cases where the Tier-1 fast scanner and the Tier-2 converter disagreed on the same input – the library picks a tier automatically, so those meant one document could convert two ways.
Test coverage behind it: every one of the 652 `CommonMark` spec examples is now exercised through a conversion-fixpoint oracle (the exact-match test compares against the spec’s own rendering, so it can only run on the 131 examples admitting a single valid form), a Tier-1/Tier-2 differential oracle over the benchmark corpus and a generated document set, and a fuzz target.
Against that fixpoint oracle, 644 of the 652 examples now round-trip unchanged with escaping enabled and 629 with the shipped defaults, up from 607 and 597. Of the 8 that remain, three are inherent to the round trip – adjacent block quotes, and adjacent lists sharing a bullet, merge under any compliant reparse whatever we emit – and the other five differ only in the byte spelling of a link destination.
### Removed
[Section titled “Removed”](#removed)
* **`htm_conversion_options_update_visitor` is gone from the C API.** The getter documented a non-null return as caller-owned data, but `ConversionOptionsUpdate` is only ever constructed through `htm_conversion_options_update_from_json`, and its `visitor` field carries a full `serde(skip)` – so `Deserialize` could never populate it and no FFI setter existed. The symbol could only ever return `0`. **Breaking for C consumers:** it disappears from `html_to_markdown.h` and from the compiled library, so a call that used to yield `NULL` at runtime is now a link error. Nothing that worked stops working. `ConversionOptions.visitor` is unaffected – it carries the same attribute but is genuinely reachable, because `htm_options_set_visitor` writes it directly, bypassing serde.
### Added
[Section titled “Added”](#added)
* CLI flags for six `ConversionOptions` fields that the library and the MCP surface already exposed but the CLI hardcoded: `--exclude-selectors`, `--url-escape-style`, `--max-image-size`, `--capture-svg`, `--no-infer-dimensions` and `--tier-strategy`. Each now defaults to the library’s own default, so an invocation that omits them is unchanged. The three image flags require `--extract-inline-images`, which they are inert without.
### Performance
[Section titled “Performance”](#performance)
* `escape_link_label` returns `Cow<'_, str>` and skips its two allocations when the text contains no `[` or `]`, which is the common case for link labels, image alt text and titles. The two-pass design is unchanged – it exists to avoid an O(n^2) `String::insert` shape.
### Fixed
[Section titled “Fixed”](#fixed-5)
* **Uppercase attribute names no longer discard link destinations and image sources.** HTML attribute names are case-insensitive, but the Tier-2 converter matched them byte-for-byte as written, so `<a HREF="up.html">link</a>` converted to bare `link` and `<img SRC="a.png" ALT="cat">` to `` – the destination and the alt text were dropped, not merely reformatted. The Tier-1 fast scanner has always compared attribute names case-insensitively, so these inputs were also a tier disagreement: the same document converted two ways depending on which tier ran. The `astral-tl` 0.8.0 parser upgrade lowercases attribute keys at parse time, which fixes both.
* **Tier-1 and Tier-2 disagreed on GFM autolinks.** `autolinks` defaults to `true` but was not gated in the Tier-1 router, and the Tier-1 scanner had no autolink branch, so `<a href="https://x.com">https://x.com</a>` converted to `<https://x.com>` on Tier-2 and `[https://x.com](https://x.com)` on Tier-1 – the library picks a tier automatically, so the same document converted two ways. Tier-1 now implements the autolink form rather than being gated off it, since gating a default-`true` option would have made the fast path unreachable for ordinary input.
* **Tier-1 could return the wrong output for an autolink whose label carried inline markup.** Tier-2 tests its autolink predicate against the tag-stripped text, so `<a href="https://x.com"><b>https://x.com</b></a>` still autolinks there; Tier-1 compared its rendered label (`**https://x.com**`), never matched, and emitted `[**https://x.com**](https://x.com)`. Tier-1 now bails to Tier-2 on this shape. The bail is guarded by a subsequence precheck so it fires only when an autolink is actually possible: on the benchmark corpus, none of the 889 scheme-href links that carry nested markup trigger it, so decorated links keep the fast path.
* **`<address>`, `<search>`, `<hgroup>` and `<center>` no longer merge into their neighbours.** All four are block-level, but they reached a pass-through handler that emits no separator, so `<address>foo</address><address>bar</address>` produced `foobar` – nothing in the output recorded that these were ever distinct blocks. `<colgroup>`, `<col>`, `<base>`, `<html>` and `<body>` share the same internal classification and are deliberately unchanged: the first three are table-internal or void metadata, and the last two wrap every document.
* **Two block containers in one table cell are separated by one space, not three.** The fast scanner emitted a hard line break between them regardless of `br_in_tables`, and the table-cell finalizer turned it into a three-space run, where the converter emits a single space under the default options.
* **Five Tier-1/Tier-2 divergences closed.** `<blockquote>` omitted its trailing blank line in the fast scanner, invisible to every existing test because they all placed the blockquote last; fixing it exposed a `<pre>` fence stripping one trailing newline where the converter strips all of them. A text node’s leading space survived at the start of a bare `<span>`/`<u>`, producing a double space across the Google Docs and WordPress fixtures. `<address>`, `<search>`, `<hgroup>` and `<center>` emitted a block separator the converter does not. Images with a lazy-load `src` and flattened nested-table pipes now agree as well.
* **An HTML comment no longer forces a redundant reparse of the whole document.** Custom elements are detected by looking for a hyphen in a tag name, but the scan treated the text inside `<!--...-->` as a tag name – `!--c--` contains a hyphen – so any document with any comment was reparsed through the repair path for nothing. On a 200-element document producing byte-identical output, a single comment cost 1.8x. Comments are near-universal in real pages, so most documents were paying it.
* **A table nested inside another table’s cell no longer destroys the inner cells.** The nested table’s own row and separator syntax was flattened into the outer cell unescaped, so its bare `|` characters were read as additional cell boundaries for the *outer* row. GFM truncates a row to the header’s column count, so the inner cells were dropped outright on reparse. The flattened content is now pipe-escaped outside code spans.
* **A run of ` ` between two inline elements survives.** A whitespace-only text node between inline siblings was collapsed to a single plain space unconditionally. `str::trim` is Unicode-aware and counts `U+00A0` as whitespace, so the run was destroyed on the first conversion, not merely on a round trip. The same collapse also ran without checking whether the output already ended in a space, stacking a real inter-element space against the synthetic one left behind by `<style>` removal into a literal double space.
* **Content written directly inside `<table>`, outside any row or cell, is no longer dropped.** HTML5’s “in table” insertion mode foster-parents such content: it moves to just before the table and survives. The parser this crate uses performs no such fixup and the table builder recognised only `caption`/`colgroup`/`col`/`thead`/`tbody`/`tfoot`/`tr` there, so raw text was silently discarded and stray elements went through a no-op handler – `<table>abc</table>` converted to nothing at all.
It appeared to work whenever a comment happened to sit nearby, but that was coincidence: a separate defect treats `!--c--` as a tag name, sees a hyphen, and reroutes any comment-bearing document through the html5ever repair path, which does implement foster parenting. The text survived by accident. That path is now entered deliberately for this shape. Comments themselves are excluded, since HTML5 keeps them as children of the table and nothing is lost.
* **Lazy-loaded images resolve to their real address instead of converting to nothing.** Lazy-loading libraries leave `src` empty or holding a 1x1 `data:` placeholder and put the actual URL in `data-src`, `data-lazy-src`, `data-original`, `data-srcset` or `srcset`, so those images came out as `![alt]()` or a base64 blob – effectively invisible on a large share of modern pages. The fallback applies only when `src` is already empty or a `data:` URI, so a plain `<img src="...">` is byte-identical to before. A populated non-`data:` `src` is trusted even when it looks like a placeholder, since some pages carry the real photo there while `srcset` holds only the lazy-load stand-in.
* **A heading inside `<summary>` or `<figcaption>` no longer splices its `#` prefix into unrelated text.** Tier-1 records a heading’s content offset against whichever buffer is active when the tag opens, and `<summary>`/`<figcaption>` accumulate into their own buffer. Only table cells were special-cased, so a heading in a `<summary>` took a small buffer-relative offset and used it to index the whole document output instead – inserting heading prefixes into the middle of already-emitted text. Rustdoc’s `<details><summary><h3 class="code-header">` shape turned `Sample` into `Samp#### #### le`. This corrupted adjacent content, not just the heading.
* **An unclosed `<table>` no longer discards its rows.** Every element still open at end of input is closed implicitly, but Tier-1’s implicit-close path did nothing for `<table>`, dropping the entire accumulated table – fully-formed rows included – where the explicit `</table>` path rendered it correctly. Text sitting directly inside `<table>` outside any row or cell is now routed to Tier-2 rather than silently discarded.
* **An empty `title=""` is treated as absent instead of rendered as `(url "")`.** The empty annotation carries no information and no Markdown serializer round-trips it, so converting the re-rendered output produced different Markdown than the first pass. Applies to links, images and graphics alike. A whitespace-only title is still a title; only a genuinely empty attribute changed.
* **HTML5 bogus comments render as nothing instead of leaking their text.** `<?php echo 1; ?>` emitted `?php echo 1; ?>`, `<!bogus>` emitted a stray `>`, and `</3>` emitted `</3>`. All three are comment tokens under the tokenizer’s tag-open, markup-declaration-open and end-tag-open states, so they render as nothing – as real `<!-- -->` comments already did. Identical constructs were rendering differently based only on which tokenizer state they happened to reach.
Most visibly this cleans up Microsoft Word HTML, whose downlevel-*revealed* conditional comments (`<![if !vml]> … <![endif]>`, not wrapped in `<!--`) were surfacing as literal noise around every image and footnote.
Real comments, CDATA, and doctypes are stepped over rather than scanned into. That matters for downlevel-*hidden* conditional comments: `<!--[if gte mso 9]> … <![endif]-->` is a real comment whose terminator is the `-->` at the end of `<![endif]-->`, so treating that `<![endif]` as bogus would delete the comment’s own terminator and swallow the rest of the document. `<).** 3.11.6 claimed this was fixed, but the strip ran only inside the paragraph handler, so it covered `<p>...<br></p>` and nothing else. Every other way an inline run can end still leaked the marker: before a following block of any kind (`A<br><p>B`, the reporter’s follow-up case, plus headings, lists, blockquotes, rules, tables and `<div>`), at the end of the document (`A<br>`), at the end of a `<div>`, list item, blockquote, `<section>`, `<details>`, `<figure>` or `<dl>`, and through nested containers.
`CommonMark` gives a hard line break no meaning at the end of a *block*, not merely at the end of a `<p>`. The check now runs wherever a block boundary is actually reached. Handlers that walk their children into a fresh buffer were each an independent instance of the same defect, because `str::trim` cannot repair a trailing `"\\\n"` – it removes the newline and leaves the backslash stranded.
Worst case fixed: in a `<figcaption>` the caption is wrapped in emphasis *after* the marker is appended, so the leftover backslash landed between the text and the closing `*` and escaped it – `<figure><figcaption>A<br></figcaption></figure>` produced `*A\*`, malformed Markdown rather than a merely visible artifact.
A `<br>` that precedes real inline content still emits its break, a leading top-level `<br>` still opens a line ([#112](https://github.com/xberg-io/html-to-markdown/issues/112)), and `newline_style="spaces"` output is unchanged – its leftover marker is invisible trailing whitespace.
* **Four cases where the Tier-1 fast scanner produced different Markdown than the Tier-2 converter for the same input.** The library picks a tier automatically, so a divergence means the same document could convert two ways depending on which path it qualified for. Tier-2 is authoritative and was correct in all four.
A custom element (any unknown tag containing `-`) was treated as block-level, so one appearing inline in flowing text split the surrounding paragraph, list item or blockquote and could leave an orphaned bullet or emphasis marker behind. Unknown elements are inline by default in HTML – there is no block-level custom element absent a CSS rule this converter does not apply – so they now pass through inline, as the DOM walker always did.
Named character references outside Tier-1’s hot subset (`∉`, `∴`, `¹`, `¶`, `™`) passed through as literal text instead of decoding. Tier-1 now falls back to the same full WHATWG named-reference table Tier-2 decodes against, rather than a hand-picked subset.
`<strong><strong>x</strong></strong>` emitted `****x****`, which `CommonMark` does not parse as strong emphasis at all; redundant same-type nesting now collapses to one marker pair. A trailing whitespace run before a closing inline marker – most often a decoded ` ` – stayed inside the markers instead of moving outside them.
A leading whitespace run inside `<strong>`/`<em>` was deleted rather than moved outside the markers, so `<p>a<em> x</em></p>` lost the space entirely: `a*x*` where the DOM converter gives `a *x*`. The trim is still applied to `<a>` labels, which really are trimmed, and to `<code>`, which is verbatim.
* **The published crate no longer ships two tests that cannot compile.** Both read the `CommonMark` spec fixture from a path outside the crate root, which `cargo package` does not carry, so `cargo test` on the packaged crate failed to build. They are excluded from the package and still run from a repository checkout.
* **Leading whitespace at the start of a document is stripped, matching every later block.** `<p> a</p>` kept its space while `<p>x</p><p> a</p>` dropped it, so the same markup converted differently depending only on whether anything preceded it. The converter had no way to tell “start of the real output” from “start of a handler’s private scratch buffer” – every inline wrapper builds its content into a fresh buffer before splicing it in – so a naive emptiness check silently changed every wrapper whose first child begins with whitespace.
* **Block children of a list item stay inside the item.** Fenced code blocks and block quotes were emitted without the continuation indentation that keeps them in the item, so they escaped the list entirely on reparse. The indent sums each open ancestor’s actual marker width rather than assuming two spaces per level, since ordered markers vary in width (`1.` against `10.`).
* **List looseness is detected as the whole-list property it is.** One blank line anywhere between items makes a compliant reparse wrap *every* item in `<p>`, but detection only looked for a literal `<p>` and missed `div`, `blockquote`, `pre`, `table`, `hr` and `dl` children and loose nested sublists. Alongside it: a nested list that is an item’s sole leading child no longer double-counts the parent marker’s width and pushes its content past the four-space indented-code threshold; a block quote following an item’s bare leading text is no longer forced onto a blank line, which had made that text round-trip as its own paragraph; a bare `<!-- -->` between two adjacent same-type lists is preserved, being the one signal that stops them merging; and the bare-marker check now honours the configured bullets instead of hardcoding `*`, `-` and `.`, having missed `+` from the default cycle.
* **A nested list keeps its line break when the text before it ends in whitespace.** `<li><strong>b </strong><ul><li>sub</li></ul></li>` collapsed to `- **b** * sub`, flattening the sublist onto the parent line so it stopped being a list at all and its content was lost. The “are we already at a bare marker” test was a two-byte suffix check, and a closing `**b**` plus its trailing space ends in the same two bytes as a real `*` bullet plus its space. Both tiers were wrong in exactly the same way, so the differential oracle could not see it; the check now requires the whole line to decompose into bare markers.
* **Non-ASCII bytes in a link destination are percent-encoded.** A raw byte at or above 0x80 is not valid URI syntax under RFC 3986, and compliant renderers encode it when writing an `href`. Only non-ASCII bytes are touched, so reserved ASCII punctuation in query strings is untouched. Same-document `#fragment` destinations are exempt: they must byte-match an element id this converter does not generate, and encoding one side of that pair would break the anchor.
* **Link-shaped text in image alt text and link labels is escaped.** Alt text is parsed as full inline content on reparse, so `<img alt="[foo](uri2)">` had its alt silently become a real nested link and lost the destination. Both ends of the pair are escaped, since escaping only the closing bracket leaves the outer `[` to be captured by a later `]` and the image then fails to form at all. A genuine nested `` inside link text is left intact.
* **A link or image with no visible text no longer turns its own href into emphasis.** Such an element falls back to the href as its label, and that fallback bypassed the text escaper, so a raw `*` or `_` in the URL round-tripped into real emphasis. Two destination-escaping gaps closed with it: a literal backslash before the paren escaping in an unbalanced-parens destination was not itself escaped, and a raw line ending inside an angle-bracket-wrapped destination is not valid `CommonMark` at all and is now folded to a space.
* **The Tier-1 fast scanner matches the Tier-2 converter on every fix above, and on a further run of divergences found by the differential oracle.** Because the library selects a tier by input shape, each divergence was a case where one document could convert two ways. Three suppressions were also removed from the oracle’s allow-list, so it now generates those shapes freely instead of avoiding them; the four that remain are each documented in place.
* **A hard line break inside a link’s visible text survives a round trip.** A `<br>` in a link label was collapsed to a space, so converting, rendering back to HTML, and converting again lost the break – yet a hard break inside link text is perfectly legal `CommonMark`. Ordinary soft newlines from wrapped source text still collapse to a space, and a break at the very start or end of a label is still dropped, having no line to break to.
* **Four more places mistook inline content for a bare list marker.** The check was a two-byte suffix test, and a closing `**bold**` plus its space ends in the same two bytes as a real `*` bullet plus its space. A block quote after inline text in a list item lost its continuation indent and fell out of the item entirely on reparse, since `CommonMark` matches containers per line; a fenced code block was glued onto the preceding inline line, where the fence is not a valid opener; a `<div>` ran straight onto the previous text with no separator at all; and Tier-1’s paragraph handler ran the check without first confirming an open list item, so top-level text merely ending in a hyphen and a space lost the blank line before the next paragraph. Several of these also omitted `+`, the third bullet in the default cycle, so they misbehaved at every third nesting level.
* **An unclosed `<p>` or `<div>` in a list item no longer swallows the next item.** `<ul><li><div></li><li>foo</li></ul>` converted to `- - foo`, turning two sibling items into one item holding a nested list, and `<ul><li><p>x</li><li>foo</li></ul>` converted to `- x- foo`, running both onto one line so the second stopped being a list item at all. Closing the tag explicitly was already correct, so this hit precisely the shape the HTML5 parsing algorithm resolves with an implied end tag – ordinary markup, not an edge case. The primary parser nests the following item under the unclosed element; the misparse detector that already re-parses such trees with the spec-compliant fallback only recognized a block nested under an *inline* ancestor, so a `div` or `p` never triggered it. Genuinely nested lists are unaffected.
* **Leading whitespace on soft-wrapped continuation lines no longer shrinks on every pass.** A run of spaces after a newline in block text collapsed to one space, but `CommonMark` strips a line’s leading whitespace entirely when assembling a paragraph, so a renderer dropped the space that was kept and the next conversion saw one fewer – the text never stabilized. Such runs now collapse to nothing, which is what a round trip already forces. Whitespace at a text node’s own edge is untouched, since that is what keeps adjacent words apart.
* **A literal backslash in a link destination is no longer swallowed.** Two shapes lost data. A backslash before ASCII punctuation was consumed as a `CommonMark` escape of that character on reparse, so `href="\*"` came back as `href="*"`. A backslash at the end of a destination with no title after it merged with the closing parenthesis into an escaped `\)`, so the destination never terminated – `href="x\"` reparsed as the literal text `[t](x)`, losing the href and the link structure and leaving raw brackets in the rendered output. Both are now escaped; a trailing backslash followed by a title’s space, which is harmless, still is not.
* **The Tier-1 fast scanner no longer emits broken output for block children of a list item.** A `<div>` inside an `<li>` came out with no continuation indent, so its content fell out of the list on reparse; `<blockquote>`, `<table>`, `<dl>`, a `<p>` continuing existing text and a `<pre>` as an item’s first content were each wrong in their own way. Under the shipped defaults Tier-1 is never reached for these, because metadata extraction and highlight styling both force the DOM converter first – but with those disabled, all six shapes diverged. Rendering them correctly needs Tier-1 to defer its separator decisions the way the DOM converter does, which also entangles the loose-list heuristic, so the scanner now declines these shapes and falls back instead. No corpus coverage is lost: the new bail never fires across either parity corpus.
* **A lone significant character after a `<br>` is no longer dropped.** `<p>a<br> </p>` kept its non-breaking space, but the same markup with a newline after the `<br>` lost it – so whether content survived depended on nothing but whether the source HTML happened to be pretty-printed. A rendered `<br>` is always followed by a literal newline, which flipped the handler into a branch that discarded the run wholesale. Separately, a `<br>` inside a heading emitted the two-space hard-break marker, which has no meaning on a single line: a renderer collapses it, so the next conversion saw different bytes. It now emits one space.
* **`br_in_tables: false` is honoured for lists inside a table cell.** Both converters emitted a literal `<br>` between sibling `<li>` elements in a cell regardless of the option, so the setting silently did nothing for the shape it most often applies to – a list in a cell, as MediaWiki sidebars produce. This also caused a round-trip instability: once a renderer flattens the list, that same `<br>` took the ordinary option path on the second pass and collapsed to a space, so the two passes disagreed.
* **A non-breaking space between two `<br>` tags is no longer dropped.** The paragraph pre-filter discarded a text node outright when trimming found it empty and both neighbours were empty inline elements – and trimming is Unicode-aware, so a lone U+00A0 counted as empty even though it is visible content. It surfaced only on a second conversion, because the source spells it ` ` (six ASCII bytes) while a renderer re-serializes it as the literal character. Only genuine ASCII whitespace is dropped there now.
## \[3.11.6] - 2026-08-28
[Section titled “\[3.11.6\] - 2026-08-28”](#3116---2026-08-28)
Re-release of 3.11.5, which never reached any registry: the publish run failed and crates.io still tops out at 3.11.4. Also carries the release-gate fixes below.
### Fixed
[Section titled “Fixed”](#fixed-6)
* **`<br>` runs emit one hard break each, and none trailing a block.** A run of consecutive `<br>` elements collapsed inconsistently, and a `<br>` immediately before a block boundary added a stray break to the output.
* **`packages/r/src/Makevars` is tracked instead of gitignored.** The file is alef-generated and alef-owned, but `packages/r/.gitignore` discarded it, so `alef verify --exit-code` – the “Verify binding freshness” step of CI Rust – failed on every run. `src/Makevars.win` stays ignored.
* **The Dart e2e before hook installs the pinned `flutter_rust_bridge_codegen`.** It hard-coded 2.12.0 while the project pinned flutter_rust_bridge 2.13.0, so CI Dart aborted on alef’s version-disagreement check. `[crates.dart] frb_version` now declares the pin explicitly next to the hook that has to match it.
### Removed
[Section titled “Removed”](#removed-1)
* Dropped a stray Python `enum_module` from the node and java e2e call overrides; neither emitter reads it.
## \[3.11.5] - 2026-08-25
[Section titled “\[3.11.5\] - 2026-08-25”](#3115---2026-08-25)
### Changed
[Section titled “Changed”](#changed-3)
* Regenerated all language bindings on alef 0.68.0.
### Changed
[Section titled “Changed”](#changed-4)
* **`alef` pinned to `0.67.5` (from `0.67.2`) and the tree regenerated.** Every one of the 609 regenerated files carries a real content change; none is a bare provenance restamp. The substantive ones: the tagged `VisitResult` wire shape is now decoded consistently across languages – Swift gains hand-written `Codable` conformance keyed on `{type, output}`, and the PyO3 bridge reads the `output` member instead of treating the whole envelope as the payload; Java’s `VisitorBridge` derives its `NodeContext` field offsets from the declared `MemoryLayout` rather than from hand-maintained byte constants, and a throwing visitor callback now returns `VISIT_RESULT_CONTINUE` instead of `VISIT_RESULT_ERROR`, so one failing callback no longer aborts the whole conversion; Kotlin/Android e2e imports lose a doubled `io.xberg.android.io.xberg.android` package prefix; the Zig e2e suite asserts exact output instead of trimming it first; and the TypeScript snippets optional-chain nullable metadata (`result.metadata?.links`).
* **Snippet gap checking is configured, so `--strict` runs it instead of erroring.** `[workspace.docs.snippets]` gained `docs_dirs` and `required_languages`, mirroring the flags `task docs:snippets:gaps` already passed. Neither was set, so the gap pass – unreferenced snippets and missing language variants – was skipped entirely, and alef 0.67.5 correctly refuses to let a strict run pass on a check that compared nothing. `alef.toml` is hashed as a generation input as a whole rather than per-surface, so adding two snippet-only keys restamped the provenance marker of all 5044 content-verified files without changing a single line of generated content.
### Fixed
[Section titled “Fixed”](#fixed-7)
* **`RustBridgeC.h` is whole again after a regeneration silently truncated it by 193 lines.** The header is a concatenation of `SwiftBridgeCore.h` and `html-to-markdown-rs-swift.h`, both produced by `cargo build -p html-to-markdown-rs-swift`. When those build artifacts are absent – as they are right after `alef all --clean` wipes them – alef emits the crate half alone and reports success, so the file lost `RustStr`, `__private__FfiSlice`, every `__private__Option*` struct and `__swift_bridge__null_pointer`. Regenerating against real build artifacts restores content byte-identical to the pre-upgrade file. Nothing about this was an alef 0.67.5 behavior change; an earlier entry in this section wrongly credited it as one.
* **The eleven hand-written TypeScript and WASM snippets now declare which session validates them.** Two sessions (`node` and `wasm`) both validate `typescript` snippets, and alef 0.67.5 stopped guessing between them; the six snippets under `docs-site/src/snippets/typescript/` now carry `target: node` and the five under `docs-site/src/snippets/wasm/` carry `target: wasm`. These eleven had never actually been compiled – they were reported as errors, not failures – which is how the WASM visitor example kept four implicitly-`any` callback parameters that `noImplicitAny` rejects the moment the snippet is really typechecked. It is now a `typescript` fence with its parameters annotated, matching the `node` example beside it and every generated WASM snippet. Snippet results move from 4550 passed / 11 errored to 4561 passed / 0 errored.
* **A skipped `publish-crates` no longer reads as a passing gate, and a release that published nothing can no longer report success.** Eight places in `.github/workflows/publish.yaml` gated downstream build, publish and release-promotion jobs on `needs.publish-crates.result != 'failure'`. That expression is TRUE when the dependency was *skipped*, and `publish-crates` skips for two opposite reasons: the version is already on crates.io (a re-run or a resumed release, where downstream must proceed) or an upstream gate such as version validation or crate packaging failed (where downstream must not). `result` alone cannot separate them, so every one of those conditions was gating on nothing – tree-sitter-language-pack v1.15.5 promoted a GitHub release to `Latest` with 40+ failed jobs and every registry publish skipped, and still reported success.
A new always-running `crates-gate` job resolves the ambiguity once, into an explicit `outcome` (`published` / `already-present` / `not-required` / `dry-run` / `blocked`) and an `ok` flag that every consumer now tests instead of `result`. Because the job always runs, its outputs always exist; because it never fails, depending on it cannot skip a consumer. The legitimate already-published path stays exactly as permissive as before, and only the gate-failed path is newly blocked.
`release-report` also stopped being able to see this class of failure: it inspected only jobs whose conclusion was `failure`, so a run where every publish job merely *skipped* passed. It now judges each target on its own result and treats `skipped` as a failure unless the target is not enabled for this release or its registry probe already found this exact version published.
* **The R vendoring script deleted the core crate’s `[lints]` without inlining anything, so the vendored copy compiled under a different lint configuration than its sources.** `scripts/ci/r/vendor-core-crate.py` copies `crates/html-to-markdown/` out of the workspace and rewrites `workspace = true` inheritance into explicit values — except for `[lints]`, which it stripped outright. The `[workspace.lints.rust]` `unexpected_cfgs` check-cfg allowlist went with it; that allowlist is what declares the crate’s own `#[cfg(...)]` gates as expected cfg names, so every gate in the vendored copy became an `unexpected_cfgs` diagnostic — silent in a default build, a hard error under `RUSTFLAGS="-D warnings"`. `missing_docs`, `unused_must_use`, `unsafe_code = "forbid"` and the whole `[workspace.lints.clippy]` policy were dropped the same way. The script now materializes the entire `[workspace.lints]` sub-tree into the vendored manifest verbatim, matching the fix alef shipped in 0.67.x for `alef publish prepare`. The extracted text is re-parsed and compared against the authoritative parse of the root manifest, so a mis-extraction fails loudly rather than silently emitting different lints. Nothing is specific to a lint or cfg name: adding a lint or a check-cfg entry to the workspace needs no change here. The script is not replaced by alef’s implementation because it runs from `packages/r/configure` at R configure time — including on end-user machines installing the source tarball from GitHub, where only Python 3 and a Rust toolchain exist.
* **The coding-agent plugin version gate never ran on the commits that cause drift.** `plugin/` sat at 3.11.3 while core shipped 3.11.4, so all 13 version declarations under `plugin/` — OpenCode, Hermes, Claude Code, Cursor, Codex, Gemini, Kimi, Factory — were a release stale. The checker for this already existed (`scripts/sync_plugin_version.py --check`, run by `CI Plugin`), but `ci-plugin.yaml`’s `paths:` filter did not list `Cargo.toml`. A release commit bumps `Cargo.toml` and nothing under `plugin/`, so the workflow was never triggered on exactly the commits that cause drift, and the gate reported nothing rather than failing. `Cargo.toml` and `.task/tools/version-sync.yml` are now in the filter, so any core bump re-runs the gate. `sync_plugin_version.py` also grew `--expect <version>`, which asserts that core *and* the plugin both equal the version being released; `publish.yaml`’s `validate-versions` job runs it against the tag, so a drifted plugin now fails the release instead of publishing a bundle that lags the version it claims to be. The 13 stale declarations are re-synced to 3.11.4.
* `task test` now runs. `tools/benchmark-harness/examples/profile_visitor.rs` imports `NoOpVisitor`, which only exists under the harness’s `visitor` feature, but the task builds the workspace with `--no-default-features` — and `cargo test` builds examples. The example is now declared with `required-features = ["visitor"]`, matching the existing `testkit` examples. Before: `task test` exited 201 with `E0432: unresolved import html_to_markdown_bench::bench::NoOpVisitor`. After: exit 0, 1422 passed / 0 failed / 126 suites.
* `task test:ci`’s `--exclude benchmark-harness` excluded nothing — that is the crate’s *directory* name; the package is `html-to-markdown-bench`. cargo reports an unmatched exclude as a warning, not an error, so the dead flag survived silently and the crate was covered on every run. Fixed in all four `rust:test:ci` invocations and sabotage-verified: with the bench crate deliberately made unparseable, `--exclude benchmark-harness` still fails the build while `--exclude html-to-markdown-bench` never compiles it.
* Dropped the trailing `fix-cjs-named-exports.mjs` step from `task alef:generate`. `@napi-rs/cli` 3.x already emits an explicit `module.exports.<name> = nativeBinding.<name>` for every runtime export, so named ESM imports resolve without it (#450). The script had also gone stale in a way that corrupts output: napi now declares enums as `export declare const enum X`, which its regex reads as a const *named* `enum`, appending a bogus `module.exports.enum = nativeBinding.enum` and re-exporting only 7 of the 20 names it used to cover.
* `alef` pinned to `0.67.2` (from `0.66.0`) and the tree regenerated. Four real codegen changes landed, plus a hash restamp of the fixture-driven snippet corpus:
* `DocumentNode.children` and `DocumentNode.annotations` are no longer `@Nullable` in the Java record. Both mirror a plain `Vec<T>` on the Rust side carrying `#[serde(default, skip_serializing_if = ...)]`; the Rust value is never `null`, so the old signature described a state the binding cannot produce. A compact constructor now normalizes a `null` deserialization to `List.of()`. All 283 `e2e/java` tests still pass — no test in this repo asserted the old null-valued contract.
* `flutter_rust_bridge` moved to `2.13.0` across `packages/dart/{pubspec.yaml,rust/Cargo.toml}`, `Cargo.lock`, and the `frb_generated.*` outputs. `e2e/dart/pubspec.lock` also picked up the `ffi: ^2.2.0` entry its `pubspec.yaml` already declared. All 283 `e2e/dart` tests pass.
* `crates/html-to-markdown-ffi/build.rs` was regenerated with the header-export path split into named helpers, which drops the `clippy::collapsible_if` hit. `cargo clippy -p html-to-markdown-ffi --all-targets -- -D warnings` is clean and all 283 `e2e/c` tests pass.
* `packages/swift/Sources/RustBridgeC/RustBridgeC.h` is now clang-formatted. Token-normalized, the file is identical to the previous content apart from `#include` ordering.
* The generated snippets under `docs-site/src/snippets/generated/` now print the fields their fixture actually asserts (`result.content`, `result.metadata.document.author`, …) instead of dumping the whole result object. This exposes an alef codegen bug: the emitter dereferences optional intermediate fields without guarding them, so the 24 `metadata_*` TypeScript snippets now fail `tsc` with `TS18048: 'result.metadata' is possibly 'undefined'` and the three Open Graph / Twitter-card Swift snippets fail on `expression implicitly coerced from 'Optional<RustString>' to 'Any'`. These are generated files, so they cannot be corrected here — the fix belongs in alef’s snippet emitter.
`alef verify --exit-code` and `poly lint .` both pass on the resulting tree.
* `alef` pinned to `0.65.0` (from `0.64.0`) and the tree regenerated with the released crates.io build (`cargo install alef --version 0.65.0 --locked`), not a local `alef` checkout — unlike the 0.64.0 repin, this is not byte-identical: `packages/elixir/native/html_to_markdown_nif/src/lib.rs`, `packages/elixir/lib/html_to_markdown/native.ex`, `packages/r/src/rust/src/lib.rs`, `packages/r/R/extendr-wrappers.R`, `packages/r/NAMESPACE`, `packages/java/src/main/java/io/xberg/htmltomarkdown/{ConversionOptions,DocumentNode}.java`, and the Dart/Swift structure e2e tests all picked up real codegen differences. `packages/r/NAMESPACE` and `packages/r/R/extendr-wrappers.R` gained `.alef-ownership.toml` records (formats with no comment syntax, so they cannot carry an inline `alef:hash:` marker) alongside the existing `packages/r/DESCRIPTION` entry. `alef verify --exit-code` and `poly lint .` both pass on the resulting tree.
* `[workspace.docs.snippets]` `dirs` only listed `docs-site/src/snippets/generated`, so the 96 hand-written snippets under `docs-site/src/snippets/<lang>/{getting-started,error-handling, table-extraction,metadata,visitor}` — the ones `usage.mdx`, `errors.mdx`, `tables.mdx` and `visitor.mdx` actually import — were never discovered by `alef snippets check`. Nothing validated they still compile and nothing regenerates them, so a reader could be shown code that no longer builds. `alef e2e snippets-migrate docs-site/src/snippets` confirms none of the 96 have a fixture-generated equivalent: the generated corpus is organized by fixture topic (`conversion`, `edge-cases`, `metadata`, `options`, `real-world`, `result`, `smoke`, `structure`, `visitor`) and emits a test-style snippet (frontmatter + `main()` + `print(result)`) aimed at compile validation, not the field-access idiom (`result.content` / `result.tables` / `result.metadata`) the narrative docs teach — so they’re kept rather than replaced. Added each language’s snippet root (not a glob) to `dirs`; this reaches only the hand-written topic dirs and does not overlap `generated/<lang>/...`, which lives one level deeper under its own subtree.
* `alef adopt "**/*" --converged-only --write` claimed ownership of 13 files that already matched (or, for `packages/r/DESCRIPTION`, could only ever match via `.alef-ownership.toml` since its format carries no comment syntax) current `alef generate` output byte-for-byte apart from the provenance marker: `.clang-format`, `packages/r/DESCRIPTION`, `crates/html-to-markdown-ffi/cmake/html-to-markdown-ffi-config.cmake`, `packages/dart/rust/Cargo.toml`, `packages/{elixir,java,kotlin-android,zig}/README.md`, `packages/ruby/html_to_markdown.gemspec`, and `test_apps/{node,wasm}/pnpm-workspace.yaml`, `test_apps/php/phpunit.xml`, `test_apps/python/pyproject.toml`. 11 of those had drifted (stale `3.11.0` version pins in READMEs/gemspec/build metadata, indentation, quoting) — `adopt` stamps the marker and leaves the drifted content as-is by design; a later `alef generate` will resync it now that ownership is recorded. `packages/kotlin-android/gradle/wrapper/gradle-wrapper.jar` could not be adopted even with `--write`: alef refuses to stamp or ownership-record any binary file, so it stays unmarked — a tool limitation, not a decision made here.
* Left every create-once seed alone: `config.m4`, `crates/html-to-markdown-php/src/HtmlVisitor.php`, `e2e/java/pom.xml`, and `e2e/kotlin_android/build.gradle.kts` (the four paths `alef generate` refused to write) plus \~20 siblings alef’s own `adopt` scan flagged the same way (Cargo/npm/gem scaffold manifests under `crates/html-to-markdown-node/{package.json,index.js,npm/*/package.json}`, `packages/ruby/spec/html_to_markdown_spec.rb`, `packages/java/checkstyle-suppressions.xml`, `packages/csharp/HtmlToMarkdown{,.Runtime}/*.csproj`, `Package.swift` / `packages/swift/Package.swift`, `packages/dart/{pubspec.yaml,CHANGELOG.md,example/*.dart}`, `packages/zig/{build.zig,build.zig.zon,test/*.zig}`). Each is a create-once seed: alef writes it only when absent, and every one on disk is substantial hand-maintained content (24-431 lines), not a placeholder. `alef adopt --clobber-create-once-seeds` would stamp them, but that flag explicitly consents to alef replacing the file with a placeholder seed on the next `generate` — the wrong trade for real content, so none of these were adopted.
* Ran `alef generate` then `alef all` to actually resync the 13 adopted files and everything else the `[workspace.docs.snippets]` `dirs` config edit (above) left stale: every alef-owned file’s provenance marker fingerprints the full config, so that one-line config change invalidated the whole generated tree’s markers even where rendered content hadn’t changed. 5 of the 13 adopted files had real drift: `packages/dart/rust/Cargo.toml` (hardcoded `version = "3.11.4"` instead of `version.workspace = true`, and missing the `[lints.clippy]` block its swift sibling carries — meaning `dbg_macro`/`print_stdout`/`print_stderr` were silently unenforced for that crate), `packages/ruby/html_to_markdown.gemspec` (stale file-exclusion glob), `crates/html-to-markdown-ffi/cmake/html-to-markdown-ffi-config.cmake` (indentation), and `test_apps/python/pyproject.toml` and `.clang-format` (missing hash marker / stale dependency pin). The other 8 already matched generated output byte-for-byte. Checked every other workspace member’s `Cargo.toml` for the same missing-lints gap: `packages/dart/rust/Cargo.toml` was the only one lacking `[lints]` entirely; all ten others already carry their own `[lints.clippy]` block or `workspace = true`. `alef verify --exit-code` now reports zero stale bindings; the remaining failure is \~99 pre-existing scaffold files (`LICENSE`, `.gitignore`, `package.json`, gradle wrapper files, …) that were never run through `alef adopt` and so carry no provenance marker — a separate, long-standing gap outside this fix’s scope, left for a future adoption pass.
* Compile-validated the 96 hand-written snippets `alef generate` (above) had just made visible to `alef snippets check`. 6 C snippets under `docs-site/src/snippets/c/` still declared `HTMConversionResult *`/`HTMConversionOptions *`/etc. as raw pointer types and compared them against `NULL`; the FFI moved to opaque `HTMAlefHandle` (`uint64_t`) handles a while ago and these were never updated, so 5 failed to compile and a 6th (`visitor/basic_visitor.md`, comparing `HTMHtmVisitor *` against a type that no longer exists) was misclassified as an unresolved dependency by alef’s error-pattern heuristic rather than a real failure. Rewrote all 6 to the handle-based idiom (`HTMAlefHandle result = htm_convert(html, 0);`). One zig snippet (`docs-site/src/snippets/zig/visitor/basic_visitor.md`) used `orelse` on `c.htm_convert`’s return value as if it were optional; the binding returns a plain `u64` (0 on failure), so `orelse` no longer type-checks — replaced with an explicit `if (result == 0) return error.ConvertFailed;`. Both languages are now 578/578 with zero failures and zero unavailable.
The hand-written `docs-site/src/snippets/typescript/*` snippets import the published package name (`@xberg-io/html-to-markdown`), same as a real consumer would, but the node and wasm snippet sessions’ `cwd` IS that package (or its sibling), so nothing had ever installed it into its own `node_modules` the way `pnpm add @xberg-io/html-to-markdown` would for a consumer. Added a `before` hook to both sessions in `alef.toml` that self-links the package (`mkdir -p node_modules/@xberg-io && ln -sfn ../.. node_modules/@xberg-io/html-to-markdown` for node; the wasm session links to the sibling node crate since the snippets never import the wasm package by name). Verified by hand that this actually fixes module resolution — `tsc --noEmit` against alef’s own synthesized session `tsconfig.json` passes clean once the symlink exists — but `alef snippets check` itself still reports these same 11 snippets (6 hand-written × node and wasm sessions, minus one overlap) as `unresolved_dependency` even after the fix and with `--cache off`. This reproduces identically across repeated fresh runs, so it isn’t cache staleness; it looks like a defect in how alef disambiguates a single fence-tag (“typescript”) claimed by two sessions when validating frontmatter-less (hand-written, not fixture-generated) snippets, since the equivalent 283-file fixture-generated batch (which does carry `target: node` frontmatter) passes cleanly through both sessions. Not fixed from this repo; documented here for upstream triage.
5 hand-written `docs-site/src/snippets/kotlin_android/*` snippets (`import io.xberg.android.*`) also remain `unresolved_dependency` even after `./gradlew assembleDebug -Palef.skipHostJni=true` succeeds and the target classes are confirmably present in `packages/kotlin-android/build/intermediates/aar_main_jar/debug/syncDebugLibJars/classes.jar`. `./gradlew publishToMavenLocal -Palef.skipHostJni=true` gets further (compiles and bundles the release AAR) but fails at `signMavenPublication` for lack of a configured signatory — this environment has no GPG signing key, and none was fabricated. Left unresolved rather than faked; the 6th kotlin_android snippet (`visitor/basic_visitor.md`) is comment-only (the visitor pattern isn’t supported on this binding yet) and reports `PASS` trivially.
`docs-site/src/snippets/feedback.md` was deliberately left out of `[workspace.docs.snippets]` `dirs`: it’s a shared MDX `<Content>` partial (a static “found a bug?” callout imported by \~10 doc pages), not a per-language code sample — it contains zero code fences, so there is nothing for `alef snippets check` to discover or validate there.
Final `alef snippets check --strict --cache off` result across all 16 configured languages: 4571 total, 4555 passed, 0 downgraded, 0 failed, 0 skipped, 0 errors, 16 unavailable (kotlin 5, typescript 11, both detailed above). `--strict`’s bar is zero *incomplete* (`Skip | Unavailable | Downgraded`), not zero failures, so this run still fails that bar — reported plainly rather than as a pass.
* The 5 kotlin_android `unresolved_dependency` snippets above were misdiagnosed: the real cause was not the classpath or the unsigned AAR, it was plain Kotlin syntax. `error-handling/basic_usage.md`, `table-extraction/basic_extraction.md`, and `metadata/basic_extraction.md` opened with (or ended in) bare top-level statements — `try { }`, a top-level `for` loop, trailing `println(...)` calls — which a plain `.kt` file (unlike a `.kts` script) does not permit outside a function body; `kotlinc` rejected them with `error: syntax error: Expecting a top level declaration`, which alef’s error-pattern heuristic then classified as `unresolved_dependency` rather than a real failure, the same misclassification already seen and corrected for the C/zig visitor snippets above. `getting-started/basic_usage.md` and `getting-started/with_options.md` were already declarations-only (`val`/`import`) and passed without change. Wrapped the executable body of the three broken snippets in `fun main() { ... }`, matching the convention the Java/C# snippets already use for the same requirement. `alef all --clean` (0.65.0, with `packages/kotlin-android` built via `cargo build --release -p html-to-markdown-rs-jni` + `./gradlew assembleDebug -Palef.skipHostJni=true`) now reports kotlin at 0 failed / 0 unavailable across all 3 (all 6 including the two already-passing and the trivial visitor snippet). The typescript disambiguation defect (11 unavailable, both `node` and `wasm` sessions claiming the same `typescript` fence tag) is unchanged at 0.65.0 and remains upstream-triaged, not fixed here.
# Changelog archive: 3.11.4–3.6.21
## \[3.11.4] - 2026-08-22
[Section titled “\[3.11.4\] - 2026-08-22”](#3114---2026-08-22)
### Fixed
[Section titled “Fixed”](#fixed)
* `alef.toml`’s `[workspace.docs.snippets]` `timeout_secs` was 120s, which also bounds every session’s `before` hook. On a cold checkout the kotlin_android (`assembleDebug`), wasm (`pnpm run build:all`) and swift (`swift build`) sessions could not finish their `before` build within that window, so their snippets were reclassified `unresolved_dependency` and reported `Unavailable` — failing CI’s `alef snippets check --strict` (`Failed: 0` but a large `Unavailable` count) even though no snippet itself was broken. Raised to 900s, matching the precedent in tree-sitter-language-pack’s `alef.toml`.
* The benchmark regression gate no longer fails at random on the CPU the runner happened to draw. `htmbench compare` compared the whole `Provenance` struct for equality, so a capture from an Intel Xeon host could not be evaluated against a baseline calibrated on an AMD EPYC host: it aborted with `benchmark provenance mismatch` before any timing was compared, even though the timings themselves passed every threshold. GitHub’s `ubuntu-24.04` label spans both vendors and the calibration campaign is `workflow_dispatch`-only, so which host each side drew was a coin flip. `cpu_model` and `cpu_count` are now excluded from the provenance contract; every other field — rustc, Cargo, profile, build flags, core features, measurement mode, tier and visitor selection, iteration/warmup settings, runner image and class — still hard-fails on drift. A differing CPU is reported instead as a host mismatch, and the new off-by-default `--allow-host-mismatch` flag (passed only by the CI regression job) downgrades timing violations to advisory on hardware the baseline was never calibrated on. Thresholds are unchanged and the baseline was not re-cut: a regression measured on the calibrated CPU still fails the run.
* The FFI Symbols CI gate is green again. It was failing on two independent findings.
The `htm_register_html_visitor` allowlist entry is retired. It claimed “visitor registration never landed in the FFI crate”, which is no longer true: registration landed as the vtable API `htm_visitor_create` / `htm_options_set_visitor` / `htm_visitor_free`, and the alef 0.62.6 regen (`4765a4139`) replaced the last phantom caller — a Java Panama `SymbolLookup.find(...)` in `NativeLib.java` — with lookups of those real symbols. The checker reported the entry as *orphaned* rather than *resolved* only because it matches on exact symbol names and the replacement uses different ones. The C# visitor surface reaches the same exports through `NativeMethods.cs` and `HtmlToMarkdownConverter.Convert`, and all 49 tests in `e2e/csharp/tests/VisitorTests.cs` pass against the built native library, so the public `IHtmlVisitor` / `HtmlVisitorBridge` API is wired end to end.
`htm_node_type_from_json` is allowlisted, replacing it. The alef 0.62.9 regen (`dc27e0560`) re-added a C# P/Invoke for it, but `NodeType` is a fieldless `Copy` enum: it crosses the C ABI as `int32_t`, so the FFI exports `htm_node_type_from_i32` / `htm_node_type_from_str` and no handle-returning `from_json`. Nothing calls `NodeTypeFromJson`, so the declaration is latent rather than a live crash. This is a re-regression — the same symbol was allowlisted and retired once before in `555a29d20`. Fixed upstream in alef’s C# backend, which now skips scalar-crossing named types when emitting handle-lifecycle P/Invokes; the entry comes out with the first regen on an alef release carrying that fix.
* A failed per-language artifact build no longer aborts the release. In v3.11.3 four `Build PHP extension (... windows-x86_64)` legs failed and nothing else did, yet the GitHub release was never promoted out of draft, never finalized and never announced, and the Homebrew bottles, `cargo-binstall` verification, Packagist trigger and asset audit never ran — 3.11.3 reached every language registry but its release page stayed a draft.
Two GitHub Actions behaviours caused it, and the publish workflow now accounts for both. A failure propagates down the entire `needs` chain, so a job’s implicit `success()` gate is false even when its own direct needs succeeded; and the propagated failure also poisons the *value* of `needs.<job>.result`, so `upload-php-pie-release` reported `failure` to downstream jobs despite concluding `success` — which is why `always()` plus `!contains(needs.*.result, 'failure')` still skipped `verify-assets`, `release-finalize` and `announce-discord`.
The release spine (`promote-release` → `release-finalize` → `announce-discord`, plus `verify-binstall` and the Homebrew bottle jobs) now gates only on jobs whose whole ancestry is release-blocking: version validation, crates.io, and the CLI and C FFI assets. Per-language artifact jobs stay in `needs` for ordering — the draft still flips only after every asset upload has settled — but their results no longer appear in any gate. `promote-release` publishes a `promoted` output for downstream jobs to gate on, because job outputs carry no failure poison.
### Added
[Section titled “Added”](#added)
* A `Report release outcome` job closes the workflow. It reads the run’s real job conclusions from the API and writes a job summary stating whether the tag shipped and naming every artifact that is missing, then fails the run if anything failed. A release that ships without one language’s binary is now red and explicitly labelled incomplete rather than silently green.
### Changed
[Section titled “Changed”](#changed)
* `Verify release assets` is a reporting gate rather than a release gate. It runs on every real tag and no longer guards itself with `!contains(needs.*.result, 'failure')`, which had skipped the asset audit in exactly the situation the audit exists for. Nothing in the release spine depends on its result.
## \[3.11.3] - 2026-08-21
[Section titled “\[3.11.3\] - 2026-08-21”](#3113---2026-08-21)
### Fixed
[Section titled “Fixed”](#fixed-1)
* Leading normalized whitespace at the start of a paragraph is no longer emitted before an image, preventing CommonMark from interpreting the image as an indented code block ([#460](https://github.com/xberg-io/html-to-markdown/issues/460)).
* The Swift crate compiles again. Codegen emitted a bare `EnumName::Variant` path for data-carrying variants when converting a Swift string back into a Rust enum, which rustc rejects with `E0533: expected value, found struct variant`; the regenerated crate routes those through per-enum string conversion helpers instead.
* The e2e freshness gate no longer fails on formatting it cannot produce. It installs Elixir, so alef’s `mix format` pass runs there as it does locally — without it the job emitted unformatted `.exs` and reported the difference as fixture staleness.
* The crates.io skip guard reads a real output again. The publish workflow asked `check-registry` for an `extra-packages` key (`cli_exists`), but a composite action propagates only the outputs it declares, so that key arrived as an empty string and the derived `all_exist` could never be true. The guard has therefore never once skipped an already-published version. It now reads the action’s declared `all-exist` output.
### Changed
[Section titled “Changed”](#changed-1)
* `packages/java/pom.xml` is alef-owned and regenerated. It had drifted out of alef’s ownership since roughly alef 0.60.x for want of a provenance marker, so this release lands the accumulated template changes at once: the file is reindented to four spaces, gains `<excludes>` / `<sourceFileIncludes>` blocks, and moves checkstyle to 13.11.0 and jackson-databind / jackson-datatype-jdk8 to 2.22.2. Those versions are alef’s pinned template defaults, not html-to-markdown-specific choices.
* All Rust dependencies taken to their latest versions (`cargo upgrade --incompatible` followed by `cargo update`): `rmcp` / `rmcp-macros` 3.1.2 to 3.1.4 plus twelve transitive bumps. Fourteen packages changed, none downgraded.
* alef pinned to 0.62.8.
* The benchmark harness now records nine timing samples with median and median absolute deviation, captures runner and toolchain provenance, and supports reviewed fixture-specific noise floors without changing the existing percentage regression thresholds ([#461](https://github.com/xberg-io/html-to-markdown/issues/461), [#462](https://github.com/xberg-io/html-to-markdown/issues/462)).
* Java’s `VisitResult` is now a plain sealed interface. Its Jackson `@JsonSerialize` / `@JsonDeserialize` annotations and the nested serializer and deserializer classes are gone; the visitor bridge marshals the type directly and never routed it through Jackson.
### Removed
[Section titled “Removed”](#removed)
* The unused Java visitor classes `IHtmlVisitor`, `HtmlVisitorAdapter` and `HtmlVisitorBridge`. They shipped alongside the live `HtmlVisitor`, `VisitorBridge` and `VisitorHandle` surface but nothing in the binding referenced them, so an implementation of `IHtmlVisitor` was never invoked. Implement `HtmlVisitor` instead.
## \[3.11.2] - 2026-08-19
[Section titled “\[3.11.2\] - 2026-08-19”](#3112---2026-08-19)
### Fixed
[Section titled “Fixed”](#fixed-2)
* The R package now builds against the vendored core crate instead of failing to resolve it. `configure` stripped the `path = ...` clause from `src/rust/Cargo.toml` and wrote a cargo source replacement to `src/rust/.cargo/config.toml`, but cargo reads `.cargo/config.toml` only from the working directory and its ancestors, and `Makevars.in` runs cargo from `packages/r/src` — so `src/rust/.cargo` is a descendant and that config was never read on any build. With the path clause gone the dependency fell through to crates.io, which did not have the workspace version. The path is now rewritten to point at the vendored copy, which needs no cargo config, no `.cargo-checksum.json`, and no complete vendor tree.
* Newlines inside a table cell no longer leak into the rendered row when `br_in_tables` is enabled ([#456](https://github.com/xberg-io/html-to-markdown/issues/456), [#457](https://github.com/xberg-io/html-to-markdown/issues/457)). The whole-cell newline backstop was gated on `!br_in_tables`, so enabling `br_in_tables` disabled the last-resort guarantee that a raw newline never reaches a cell. Two consequences: a `<pre>` inside a cell now renders inline, dropping its fence, indentation and language info string, matching how headings and list items already render in cells; and under `WhitespaceMode::Strict` a newline inside a cell now folds to a single space. Every other whitespace byte is still preserved exactly under `Strict`, and text outside table cells is unaffected.
* The Tier-1 fast path now honours `br_in_tables` inside table cells. It previously emitted a sentinel that always expanded to three spaces, ignoring the option, so a document routed through Tier-1 could render `<br>` in a cell differently from the same document routed through Tier-2. Tier-1 also folds a text node’s trailing newline the way Tier-2 does, fixing cells that were double-spaced against Tier-2 when the source HTML was pretty-printed across several lines.
* A literal backslash in HTML prose is no longer silently lost when the Markdown is read back ([#458](https://github.com/xberg-io/html-to-markdown/issues/458)). CommonMark consumes a backslash that precedes ASCII punctuation, so emitting `3\*4` from `<p>3\*4</p>` produced Markdown that reparsed as `3*4` — the source character was gone. Such a backslash is now doubled, and so is one that sits immediately before a line ending (where CommonMark would read it as a hard line break) or at the end of a text run (where whatever the emitter appends next would become its escape target). This changes output under default options: any document whose prose contains a backslash in one of those three positions gains a second backslash there. A backslash before anything else is already literal and is still emitted bare, so Windows paths such as `C:\Users\Alice` are unchanged. Code spans, code blocks and link titles are also unaffected — the first two are verbatim by design and the third already escaped backslashes through its own rule. The escape is deliberately not gated behind `escape_misc` or `escape_ascii`, because it preserves a character the source actually contained rather than neutralising Markdown syntax the way those flags do.
## \[3.11.1] - 2026-08-15
[Section titled “\[3.11.1\] - 2026-08-15”](#3111---2026-08-15)
> Prepared but never published: no `v3.11.1` tag was pushed and no 3.11.1 reached crates.io, so 3.11.0 is followed directly by 3.11.2. The entries below ship as part of 3.11.2.
### Upgrade note — the C ABI changed
[Section titled “Upgrade note — the C ABI changed”](#upgrade-note--the-c-abi-changed)
This release changes the C header, so it is not drop-in for C, Go (cgo) or any other consumer that links the native library directly. Rebuild against the new header rather than reusing an existing build. Managed bindings (Python, Node, Ruby, PHP, Java, C#, Elixir, R, WASM) are unaffected.
* `HTMHtmHtmlVisitorBridge` and `HTMHtmHtmlVisitorVTable` are gone. Borrowed types that cannot enter the process-global handle registry are no longer exported, so the bridge entry points `htm_htm_html_visitor_bridge_new` and `htm_htm_html_visitor_bridge_free` are removed with them. Use the `HTMHtmVisitorCallbacks` vtable instead.
* `htm_free_bytes` is removed. The exported function count goes from 307 to 304.
* `HTMHtmVisitorCallbacks` gains a `void (*free_string)(char*)` member, which changes the struct layout. Any code that constructs this struct must be recompiled, and callers that hand out heap strings from a callback should set it so the library releases them with the matching allocator.
The header previously in the tree described a surface the sources had already stopped providing; it is now regenerated from them.
### Fixed
[Section titled “Fixed”](#fixed-3)
* The generated FFI, Swift and Node sources did not compile, so the native library, the Swift package and the Node addon could not be built from a checkout. A comment-reflow pass had merged `unsafe {` into the preceding `// SAFETY:` comment at 40 sites in the FFI bridge and collapsed a doc block in the Swift bridge over the `SwiftHtmlVisitorWrapper` declaration, so neither file parsed; the Node addon applied a napi `getter` to three free functions, which napi allows only inside an `impl` block. This also blocked every commit to the repository, because the pre-commit hook compiles the staged snapshot and the FFI build script runs cbindgen over `lib.rs`.
* The FFI null-safety test called `htm_htm_html_visitor_bridge_free`, a symbol the crate had deliberately stopped exporting, so the test target did not build.
## \[3.11.0] - 2026-08-13
[Section titled “\[3.11.0\] - 2026-08-13”](#3110---2026-08-13)
### Upgrade note
[Section titled “Upgrade note”](#upgrade-note)
Rendered Markdown output changes in this release. The CSS-hidden/`hidden`-attribute fix below alone moved 56 of the 116 benchmark oracle snapshots when they were reblessed, and roughly a dozen other correctness fixes in this range shift output for the documents they affect — 64 of the 116 snapshots changed in total. Consumers who pin byte-exact golden files against this library’s output should expect to regenerate them when upgrading past this release.
A further 16 snapshots moved when hidden-element detection was corrected to read attribute structure instead of scanning raw tag text. Every one of those 16 **restores content that was previously deleted**: a Wikipedia link whose `title` attribute contained the word “hidden” was being stripped in full. If you saw links or sections disappear from converted pages, this is why.
### Added
[Section titled “Added”](#added-1)
* Documentation snippets are generated from the complete E2E fixture corpus with Alef 0.60.2 and checked for fixture-by-language coverage parity in local tasks and CI; strict validation is scoped to the generated root so the 85 maintained examples remain independently audited.
* The MCP server validates its inputs, bounds its HTTP surface and is instrumented. It previously had no instrumentation at all despite being a public RPC surface: a failed request returned an error to the client and left no trace. There are now debug spans on `convert_html` and `extract_metadata` (re-entered inside `spawn_blocking`, which does not inherit the caller’s span), warnings on rejected enum values and conversion errors, and an error event on a panicking blocking task. Behaviorally, unknown enum values from a client are rejected instead of silently falling back to a default, a `max_depth` that does not fit `usize` warns instead of silently becoming `usize::MAX`, five serialization fallbacks that returned `null`/`[]` on failure now report the failure, and the HTTP transport gained a body-size limit, a concurrency cap, a request timeout, and Origin/Host checks.
* `VisitResult` now serializes with an adjacently tagged, snake_case wire schema (`{"type": …, "output": …}`), so every binding encodes against one documented shape instead of inventing its own. The field names are public API and a conformance test pins them.
### Changed
[Section titled “Changed”](#changed-2)
* Table rendering: each cell’s Markdown is now produced once and reused between the column-width pre-pass and the render pass, instead of being rendered twice, for the common case (no nested table, no visitor installed). Rendered Markdown is unchanged — reblessing the benchmark oracle snapshots before and after produced byte-identical output. This also fixed the metadata collector recording every element inside a `<td>` twice, once per pass, on the default extraction path. See `crates/html-to-markdown/tests/table_cell_metadata_duplication_test.rs`.
* Link handling: fewer anchor traversals and allocations per `<a>` element. Output-neutral.
* Removed the internal `text_content` LRU cache and with it the `lru` dependency. Because every caller needs an owned `String`, a cache hit still cloned, so the cache cost an allocation per miss and saved none; after the table change above, the dominant table path cannot hit it at all. Measured 3.7% faster across the 29-fixture benchmark. Output-neutral.
* DOM context building: the per-document context maps (parent, children, sibling-index, and related lookup tables) are now sized once from the arena’s node count up front instead of growing incrementally as new node ids are seen. Output-neutral.
* `alef` is pinned to `0.60.2` for binding generation, in `alef.toml` and in the CI lint workflow. The two had drifted apart (`0.60.2` locally, `0.60.1` in CI), so CI generated with a different generator than every developer.
* `poly`’s whole-project lint phase is now disabled through `[workspace.poly] lint-workspace` in `alef.toml` rather than a hand-edit to the generated `poly.toml`. The shared CI validate job installs only Rust/Python/Java, so the remaining whole-workspace linters cannot run there; they run via the pre-commit hooks and each language’s own CI job. The previous hand-edit did not survive `alef all --clean`.
* Dependency upgrades, including `base64` and `tower-http` to their next major versions.
* `html-to-markdown-cli` gained optional `mimalloc` and `jemalloc` global-allocator features (`--features mimalloc` / `--features jemalloc`). Neither is enabled by default; if both are enabled, `jemalloc` takes precedence, so `--all-features` builds continue to work.
* `mcp-http` is no longer a default feature of `html-to-markdown-cli`. It was on by default, so a CLI installed via brew, cargo, npm or pip shipped the ability to start an unauthenticated HTTP service. Build with `--features mcp-http` if you need it; stdio `mcp` stays on by default, since it opens no listening socket.
### Fixed
[Section titled “Fixed”](#fixed-4)
* `<br>` inside a table cell no longer depends on `newline_style` or on the source HTML’s own whitespace ([#453](https://github.com/xberg-io/html-to-markdown/issues/453)). Two separate defects: with `br_in_tables: false` the `<br>` fell through to the paragraph hard-break path and emitted `newline_style` bytes into the cell, leaking a literal `\` under `Backslash` and a stray extra space under `Spaces`; and a newline in the source before the `<br>` survived normalization, so with `br_in_tables: true` it reached the output as a real newline and split the row’s pipe syntax across physical lines, corrupting the table. A cell cannot contain a hard line break, so `<br>` now collapses to a single space, or renders as a literal `<br>` when `br_in_tables` is enabled, in every combination of the two options and regardless of source formatting.
* `<div>` and `<p>` continuations inside a table cell follow the same rule as `<br>` ([#454](https://github.com/xberg-io/html-to-markdown/issues/454)). The two disagreed with each other: a `<div>` continuation honoured `br_in_tables` but emitted `newline_style` bytes, which are not valid inside a cell, while a `<p>` continuation always emitted `<br>` and ignored `br_in_tables` entirely. Both now emit a literal `<br>` when `br_in_tables` is enabled and collapse to a single space otherwise, sharing one code path with the `<br>` handler.
* A `<code>` span inside a table cell no longer corrupts the row ([#455](https://github.com/xberg-io/html-to-markdown/issues/455)). Verbatim content — `<code>`, and `<kbd>`/`<samp>`, which share the same path — skipped cell whitespace handling entirely, so a newline inside the span reached the output and split the row’s pipe syntax across physical lines whenever `br_in_tables` was enabled. Line breaks in that content are now folded to a single space, independent of `whitespace_mode`, because a raw newline in a cell is a structural impossibility in GFM rather than a formatting preference. All other whitespace, including repeated spaces, is still preserved byte-for-byte, and code spans outside a table cell are unaffected.
* Document-structure and inline-image collectors also record table-cell content exactly once. Images, code blocks and nested tables inside a `<td>` were recorded up to three times with `include_document_structure: true`, and inline images twice with `extract_images: true`. Note the companion change: a table that renders to nothing (a blank table, or one a visitor skips) now contributes nothing to `document` or the inline-image set, matching what it emits; `result.tables` still reports its grid.
* Metadata extracted from inside a table cell (links, images) is now recorded exactly once in every configuration. Previously a link in a `<td>` was recorded twice with `link_style: Reference`, and three times with `include_document_structure: true`, because the column-width pre-pass, the render pass, and the document-structure grid walk each re-walked the cell through a shared collector. The internal passes no longer record; exactly one walk does. Affects `metadata.links` / `metadata.images` counts for documents with tables — de-duplication on the consumer side is no longer needed.
* Rows with more cells than the header no longer lose them. The separator row was sized from the first row alone, so any later row with more cells had the surplus silently dropped by compliant renderers; it is now sized from the table-wide maximum and every row is padded to match. Separately, `scan_table_node` counted nested tables and rows transitively across nested `<table>` boundaries, so the layout-table heuristic misfired for every level of a nested chain except the innermost, turning real table structure into a mix of bullet lists and stray pipe text.
* Consecutive `<li>` elements inside a table cell no longer fuse into one word. A cell strips list markers, and nothing separated the items, so `<li>a</li><li>b</li>` rendered as the fabricated word `ab`. Both tiers now emit the same `<br>` boundary already used between sibling `<p>`/`<div>` in a cell.
* Content that a browser never renders is no longer emitted. `<template>` and `<noscript>` fell through to the unknown-element handler, which recurses into children and renders their text — a template’s contents are inert per spec and must never appear in the output — and `strip_hidden_elements` honoured only the `hidden` attribute, so `style="display:none"` and `visibility:hidden` leaked in full. This is the single largest source of output drift in this release: it alone moved 56 of the 116 benchmark oracle snapshots. `aria-hidden` is deliberately untouched, because that content is visually rendered and hidden only from assistive technology.
* Hidden-element detection no longer misreads the tag it is inspecting, in three separate ways. `declaration_hides_element` split each declaration on the first `:`, so a CSS comment ahead of the property name left `/* note */ display` as the property and never matched — `<div style="/* note */ display:none">SECRET</div>` emitted its content; comments are now stripped before the split. `tag_has_hidden_attribute` scanned the raw tag text for the word `hidden` and matched inside quoted values, so a perfectly visible `<div title="… hidden from search engines">` was deleted whole; it now walks `name=value` pairs and matches attribute *names*. And `tag_has_hidden_style` used `.any()` over declarations, ignoring the CSS cascade, so `display:none; display:block` was stripped even though the last declaration wins; it now resolves per property. The second of these is why 16 oracle snapshots gained content back — see the Upgrade note.
* Content nested inside a CSS-hidden element (`style="display:none"` / `visibility:hidden`, or the `hidden` attribute) no longer leaks into the output when the hidden element contains a nested element of the *same* tag name (e.g. a hidden `<div>` containing another `<div>`). The stripper previously matched the closing tag of the *inner* element rather than the outer one, so text after the inner close tag — and, for deeper nesting, several more layers of “hidden” text — was emitted as if it were visible. This affects any document with same-tag-name nesting inside a hidden element, including a common Wikipedia infobox pattern; see `crates/html-to-markdown/tests/hidden_element_nesting_test.rs` for the affected shapes. Output changes for documents that hit this pattern.
* Hidden content no longer escapes through a `</tag>` sequence that is not really markup. The depth-counting stripper still treated any `</tag>` byte sequence as a close tag, so four measured shapes leaked against the release binary on default options: a `<!-- </div> -->` end-of-block marker (an ordinary authoring idiom, requiring no crafting) leaked the trailing text, a quoted attribute value containing `</div>` leaked, a `</div>` inside a preserved `application/ld+json` raw-text body leaked, and an unbalanced `<div>` inside a comment inflated the depth counter far enough that the scan overshot and dropped the following visible sibling. The scan now skips comments, CDATA and raw-text bodies, and advances non-target tags through a quote-aware tag-end search.
* Alt text, titles and media URLs are escaped before they are spliced into Markdown. The hardening applied to `<a href>` was never propagated to images, graphics or embedded media, so inert input produced live output: an alt of `a](https://evil.example)` emitted a real image pointing at that URL; `<audio>`, `<video>` and `<iframe>` used `src` as both label and destination with no escaping at all; `<graphic>` had no paren handling whatsoever; and a bare quote in a title closed the Markdown title early, leaving the remainder to parse as document text. The `<a>` path’s `append_url_destination` and `escape_markdown_title` are now shared by all of them, so balanced-paren checking (which had treated `)(` as balanced) guards image destinations too. Alt and title text containing brackets or quotes is now escaped, which changes output for benign documents as well.
* The HTML serializers are depth-bounded and quote-safe. `serialize_element`/`serialize_node` in the SVG and utility paths mutually recursed over arbitrary-depth subtrees with no depth parameter at all — a remote stack overflow, reproduced as a SIGABRT with 50k nested `<g>` or `<mrow>` — and are reachable from roughly twenty call sites via `preserve_tags` and the visitor’s `PreserveHtml` result. They now truncate with a warning at the native stack-safe depth. Both also re-quoted every reconstructed attribute with double quotes without escaping an embedded one, so a single-quoted attribute holding a literal quote — valid, inert HTML — reconstructed into extra live attributes, turning an inert `title` into a real `onclick` handler. Values are now escaped regardless of the source delimiter.
* Deeply nested documents no longer exhaust the machine. Three separate defects made the depth guard ineffective: roughly two dozen call sites forwarded the recursion depth unchanged while descending into a child, every table-cell walk passed a literal `0` and so reset the budget at each cell boundary (a remote stack-overflow SIGSEGV from repeated `<table><tr><td>`), and two passes outside the depth-bounded walk were quadratic in nesting depth — `has_inline_block_misnest` ran once per block node and walked to the root each time, and `scan_table_node` re-walked the whole remaining nested-table chain from every table. A 220KB document of 20k nested `<div>`s went from 30.5s to 0.06s, and 50k-deep table, div, svg, ol and blockquote payloads — three of which previously ran past two minutes — now all finish in under a second. This was remote resource exhaustion: the guard bounded the walk but not these passes.
* A code block containing a run of three or more backticks — an embedded Markdown sample, say — no longer closes early and corrupts everything after it. The opening fence was hardcoded to three characters; its length is now `max(3, longest_run + 1)`. Inline code spans use a different rule on purpose: the smallest delimiter length not present in the content, because CommonMark closes a span at a backtick string of the *same* length, so `max_run + 1` would over-escape (CommonMark examples 330 and 331).
* An out-of-range `<ol start>` no longer panics the whole conversion. `start` was parsed as `usize` with an unchecked per-item increment, so `start="18446744073709551615"` with a single `<li>` overflowed and failed the entire document rather than just the list. The counter is now `i64`, so a negative start counts down as browsers do, out-of-range magnitudes clamp with a warning, and the increment pins at `i64::MAX` instead of wrapping. The saturation warning fires once per list rather than once per item, so a long list cannot flood the logs.
* Blockquotes preserve significant leading whitespace. The per-line loop trimmed every content line, so indented code blocks and nested-list continuations inside a `<blockquote>` lost their indentation entirely; only whitespace-only lines are blanked now. Nested blockquotes also pushed a hardcoded three newlines regardless of what preceded them, emitting stray blank `>` lines, and a paragraph following bare inline text inside a blockquote merged onto the same line because the separator was gated off inside blockquotes altogether. The gate is now depth-aware, which leaves the compact heading-then-paragraph style alone (CommonMark example 228 depends on it).
* A list nested inside an ordered list is now indented to its parent marker’s content column instead of a uniform `list_depth * list_indent_width`. That uniform width happens to match `"- "` but not `"1. "` (3 columns) or `"10. "` (4), so a nested ordered list was indented 2 columns and CommonMark parsed the child as a sibling of its parent. The indent is now the cumulative width of the ancestors’ own markers, with `list_indent_width` as the floor.
* A panicking visitor callback no longer poisons the handle for every later call. The panic unwound out of `convert()` and left the visitor’s `Mutex` poisoned, so every subsequent conversion reusing that handle failed permanently. The pipeline now runs under `catch_unwind` and clears the poison flag, confining the failure to the call that caused it.
* Three inline-image options finally do something. `InlineImageConfig::new` seeded its own defaults and the conversion path never overwrote them, so `capture_svg`, `infer_dimensions` and `max_image_size` were inert despite each having both a builder setter and an update field — and two of those internal defaults were the inverse of the documented ones: `capture_svg` documented `false` but always behaved as `true`, and `infer_dimensions` documented `true` but always behaved as `false`. `max_image_size` was ignored outright and only ever coincided with the internal constant. Callers who set any of the three will see behavior change to what the documentation always promised.
* The Tier-1 byte-scanner path agrees with Tier-2 again. It carried independently duplicated copies of the code-fence and inline-delimiter bugs fixed above, had no depth ceiling, silently returned an empty `result.metadata`, emitted hidden elements that Tier-2 strips, and left link, image and SVG-title labels unescaped — the last being the injection vector Tier-2 has guarded for some time. It also evaluated only one of Tier-2’s three layout-table conditions, so a `<table border="0">` with a `colspan`, or two nested tables, produced a GFM table (in the nested case, a malformed one) where Tier-2 produced a bullet list. Tier-1 now bails on both shapes rather than reimplementing them, and the router defers to Tier-2 for metadata rather than maintaining a second collector — a second implementation of that collector is precisely what produced the duplicated fence bugs. Default options never reach Tier-1, so this affects only callers who force `TierStrategy::Tier1` or disable metadata extraction.
* Python visitor callbacks now honor the documented `type`/`output` action dictionaries for custom link output and image `skip`/`continue` actions ([#452](https://github.com/xberg-io/html-to-markdown/issues/452)).
* Dart: the native loader downloads and caches the library again on a cold cache. It only read the versioned cache and then threw a `StateError`, even though `nativeDownloadAndCacheLibrary()` was defined and exported for exactly that case — so a machine that had never run `dart run h2m:download_libs` could not self-heal. The loader also now searches for the `_dart`-suffixed cdylib that is actually built, opens every candidate by absolute path (a hardened runtime rejects a relative `dlopen`), walks up from `Platform.script` to find the package root as a last resort, and names the real environment variable in its error message instead of printing the identifier `$nativeLibDirEnv` literally. Fixed upstream in alef 0.55.6.
Behavior change: an unresolvable native now throws a descriptive `StateError` naming the asset URL and the download command, where it previously returned `null` and let flutter_rust_bridge attempt its own relative-path `dlopen` — which would fail anyway, but later and less legibly.
* Java: `TierStrategy` serializes to the wire names the core actually accepts. Alef 0.55.7 changed the Java backend’s no-`rename_all` fallback to emit variants verbatim, but it could not see `rename_all` when it sat behind a `cfg_attr` with an `any(...)` condition — exactly how `TierStrategy` declares it. The generated Java therefore sent `Auto` to a core that deserializes `auto`, and every Java conversion failed with `unknown variant`. Fixed upstream in alef 0.55.8, which parses the `cfg_attr` condition structurally.
* CI: the Node e2e job no longer runs the Rust test suite. It invoked `task rust:test` (`cargo test --release --no-default-features --workspace`), a full release-mode build that took 3047s of the job’s 60-minute budget on `windows-latest` and left `Install alef` to be cancelled mid-step — the Windows Node e2e job had never once completed. `CI Rust` already runs the suite on ubuntu, windows and macos via `task rust:test:ci` and compile-checks `--no-default-features` separately, and no other language’s e2e job ran it. The job now passes in 925s.
* Node: the named ESM re-exports that work around napi’s `module.exports = nativeBinding` tail (#450) are now committed in `crates/html-to-markdown-node/index.js`, not only appended at publish time. `cjs-module-lexer` cannot analyse that tail, so `import { convert } from ...` broke for anyone consuming the repo directly. Published packages were already correct — both `task alef:generate` and the publish workflow run the fixup script — but the committed file was not, which also meant a regenerate-and-diff freshness check could never pass.
* `--newline-style`, `--code-block-style` and `--bullets` all documented the wrong default in the CLI’s `--help`, so users following the help text got output they did not expect. Tests now assert the real defaults, so help text and behavior cannot drift apart silently again.
* The CLI’s outbound User-Agent is derived from the crate version. It was a literal pinned at `2.10` while the crate shipped `3.10.x`, so every fetch advertised a version four majors stale.
* The coding-agent plugin’s launcher downloads the right asset and verifies it. It fetched `html-to-markdown-<triple>` while releases publish `cli-<triple>`, so every download 404’d and silently fell through to the slow path — the fast path had never once worked — and it then executed whatever it did fetch, with only TLS vouching for the bytes. It now resolves the checksum from `cli-SHA256SUMS`, retries while GitHub propagates release assets, and refuses to execute a binary it cannot verify.
* The Dart, Swift and Zig package READMEs are full documents again (276 / 271 / 260 lines). A partial generator run had replaced all three with fallback stubs of \~30 lines; Dart’s stub was the pub.dev landing page rather than the package README.
* Internal: `strip_css_comments` uses `let ... else` instead of a single-arm `match`, which was a `clippy::single-match-else` error under `-D warnings` and failed the workspace clippy gate.
## \[3.10.6] - 2026-08-05
[Section titled “\[3.10.6\] - 2026-08-05”](#3106---2026-08-05)
### Fixed
[Section titled “Fixed”](#fixed-5)
* Node.js: the `linux-x64-musl` and `linux-arm64-musl` packages really are published now. 3.10.5 added them, but both cross-compiles failed to link (`cannot find libgcc_s.so.1`) and, because the npm publish job requires every matrix leg, no Node package reached the registry at all. The build action exported `CC`/`CARGO_TARGET_*_LINKER` pointing at `musl-gcc`, and cargo-zigbuild only sets those when they are unset, so the zig cross-compile was silently replaced by a host-arch musl-gcc that cannot produce a musl cdylib. The musl legs now opt out of that export.
### Added
[Section titled “Added”](#added-2)
* CI: the musl Node cross-compiles are built on every core/node change instead of only at publish time, and the job fails if a platform package ends up without a native module.
## \[3.10.5] - 2026-08-05
[Section titled “\[3.10.5\] - 2026-08-05”](#3105---2026-08-05)
### Fixed
[Section titled “Fixed”](#fixed-6)
* Node.js: the `linux-x64-musl` and `linux-arm64-musl` packages are now built and published. They were advertised in the main package’s `optionalDependencies` but never produced, so Alpine and other musl installs silently fell back to no native binding, and `pnpm install --frozen-lockfile` could not resolve them.
* Ruby: the gem no longer publishes its generated types into the global `Object` namespace, which collided with unrelated libraries (notably the `parser` gem’s `Parser` constant). Generated types now stay namespaced under `HtmlToMarkdown` (tree-sitter-language-pack issue #173).
* Documentation: every code snippet in the READMEs, the docs site, and the coding-agent plugin references was executed against the real API and corrected. The Rust README’s metadata and custom visitor examples did not compile, the Rust API reference showed `Result<_, Error>` instead of `Result<_, ConversionError>`, the docs site shipped 102 empty language tabs across five pages, and several bindings’ snippets referenced helpers that no longer exist.
## \[3.10.4] - 2026-08-04
[Section titled “\[3.10.4\] - 2026-08-04”](#3104---2026-08-04)
### Fixed
[Section titled “Fixed”](#fixed-7)
* Node.js: named ESM imports such as `import { convert } from "@xberg-io/html-to-markdown"` now resolve. The napi-generated `index.js` ended with `module.exports = nativeBinding`, which Node’s ESM↔CJS interop (`cjs-module-lexer`) cannot statically analyze, so named imports threw `SyntaxError: The requested module ... does not provide an export named 'convert'`. The build now appends explicit `module.exports.<name> = nativeBinding.<name>` re-exports for every public runtime export; `require()` is unaffected ([#450](https://github.com/xberg-io/html-to-markdown/issues/450)).
## \[3.10.3] - 2026-08-04
[Section titled “\[3.10.3\] - 2026-08-04”](#3103---2026-08-04)
### Fixed
[Section titled “Fixed”](#fixed-8)
* The Swift package now builds under Xcode/XCBuild, not just `swift build`. The `RustBridgeC` target was header-only, so XCBuild failed to link (`RustBridgeC.o` was never emitted) for every iOS/macOS consumer of the published SwiftPM package. It now ships a translation unit with an anchor symbol so the object is always produced ([#449](https://github.com/xberg-io/html-to-markdown/issues/449)).
### Changed
[Section titled “Changed”](#changed-3)
* The PHP binding sources now live in the `html-to-markdown-php` crate alongside the other in-crate bindings; the standalone `packages/php` layout has been removed. Composer consumers are unaffected.
## \[3.10.2] - 2026-08-01
[Section titled “\[3.10.2\] - 2026-08-01”](#3102---2026-08-01)
### Added
[Section titled “Added”](#added-3)
* `cargo binstall html-to-markdown-cli` support (#448) — prebuilt CLI binaries can now be installed directly from GitHub Releases without compiling from source. Adds `[package.metadata.binstall]` to the CLI crate plus a release-time `verify-binstall` CI job that installs via `cargo binstall` and smoke-tests the binary.
### Changed
[Section titled “Changed”](#changed-4)
* Updated dependencies.
## \[3.10.1] - 2026-07-31
[Section titled “\[3.10.1\] - 2026-07-31”](#3101---2026-07-31)
### Fixed
[Section titled “Fixed”](#fixed-9)
* The Android AAR (`io.xberg:html-to-markdown-android`) now bundles its JNI native libraries. Previously the published AAR contained no `.so` files, so every consumer crashed at runtime with `UnsatisfiedLinkError: library "libhtm_jni.so" not found` ([#446](https://github.com/xberg-io/html-to-markdown/issues/446)). The publish workflow built the wrong crate (the C-FFI `html-to-markdown-ffi`) and uploaded it from a path the build action never wrote, staging nothing. It now builds the JNI crate (`html-to-markdown-rs-jni` → `libhtm_jni.so`) and stages it for every ABI, and a regenerated Gradle guard (alef 0.48.16) fails the build if a correctly-named `lib*_jni.so` is ever missing.
### Added
[Section titled “Added”](#added-4)
* The core library now emits structured `tracing` spans and events as a first-class observability surface: an `html_to_markdown::convert` span (`input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, `tier_strategy` fields) wraps every conversion, with `DEBUG` events at parse/walk/render stage boundaries and `WARN`/`ERROR` events on recovered or fatal failures. The library never installs a subscriber — attach one in your application to observe it. The CLI now initializes a `tracing-subscriber` (respecting `RUST_LOG`, with `--debug` raising the default level) and routes all diagnostics through `tracing` instead of raw `stdout`/`stderr` writes.
### Changed
[Section titled “Changed”](#changed-5)
* Android AAR now ships four ABIs (`arm64-v8a`, `x86_64`, `armeabi-v7a`, `x86`).
* Upgraded dependencies to latest, including `base64` 0.23 and `rmcp` 3.0.1.
## \[3.10.0] - 2026-07-30
[Section titled “\[3.10.0\] - 2026-07-30”](#3100---2026-07-30)
### Changed
[Section titled “Changed”](#changed-6)
* Upgraded the MCP server to `rmcp` 3.0 (MCP `2026-07-28` specification). The server now advertises protocol version `2026-07-28` and negotiates down for older clients, so existing integrations keep working. Minimum supported Rust version is now 1.88.
### Added
[Section titled “Added”](#added-5)
* Structured tool output (SEP-2106): `convert_html` (with `json:true`) and `extract_metadata` now return `structuredContent` alongside the text JSON, so clients can consume the result as data.
* Cache hints (SEP-2549) on the static prompt/resource catalogs (`prompts/list`, `resources/list`, `resources/read`): `ttlMs` of one hour with a `public` cache scope.
## \[3.9.2] - 2026-07-27
[Section titled “\[3.9.2\] - 2026-07-27”](#392---2026-07-27)
### Fixed
[Section titled “Fixed”](#fixed-10)
* Java (Maven Central) and C# (NuGet) publishing, which failed in 3.9.1. Regenerated all language bindings on alef 0.48.4: the generated pom’s Maven enforcer floor no longer exceeds the CI runner’s Maven version, and the C# package now renders `runtime.json` (from the newly generated `runtime.json.template`) before `dotnet pack` via the `xberg-io/actions/render-runtime-json` step.
### Changed
[Section titled “Changed”](#changed-7)
* Upgrade dependencies to their latest incompatible versions.
## \[3.9.1] - 2026-07-26
[Section titled “\[3.9.1\] - 2026-07-26”](#391---2026-07-26)
### Changed
[Section titled “Changed”](#changed-8)
* Refine the depth-limit warning (#434): the `DepthLimitExceeded` message now reports the effective limit value, and the warning is emitted exactly once when a deeply-nested DOM is truncated. Thanks @br411 (#428).
* Regenerate all language bindings on alef 0.48.2.
* Update dependencies to their latest compatible versions.
### Removed
[Section titled “Removed”](#removed-1)
* Remove unused Java PMD ruleset and stale linter configuration.
## \[3.9.0] - 2026-07-19
[Section titled “\[3.9.0\] - 2026-07-19”](#390---2026-07-19)
### Added
[Section titled “Added”](#added-6)
* **Configurable traversal-depth ceiling** (#434): callers may now raise the recursion limit above the conservative native default (64) by setting an explicit `max_depth`, honored up to an internal backstop of 1024. Deeply-nested email HTML that previously lost content past depth 64 now converts. When the limit does truncate a subtree, a `DepthLimitExceeded` warning is surfaced instead of the content being dropped silently.
### Fixed
[Section titled “Fixed”](#fixed-11)
* **`<br>` in table cells with `br_in_tables`** (#429): a `<br>` inside a table cell now emits a literal `<br>` (valid single-line GFM) instead of a physical newline that broke the row.
* **Newline-only inline span separator** (#430): in normalized whitespace mode a `<span>` whose sole content is a newline now collapses to a single separating space instead of being dropped, so adjacent inline text no longer glues together.
* **Paragraph after a table inside a blockquote** (#431): the span newline-pop no longer crosses a table-row boundary, so a following paragraph is not glued onto the delimiter row.
* **Intentional hard break inside a span** (#432): the span newline-pop no longer eats a `<br>` hard break (` \n` / `\\\n`), preserving the line break.
* **`keep_inline_images_in` inside layout-table cells** (#433): images inside a `td`/`th` listed in `keep_inline_images_in` now stay as markdown when a Tier-2 layout table converts cells as inline, instead of reducing to alt text.
### Changed
[Section titled “Changed”](#changed-9)
* Regenerate all bindings with alef 0.37.0.
* Update dependencies across language packages.
## \[3.8.3] - 2026-07-09
[Section titled “\[3.8.3\] - 2026-07-09”](#383---2026-07-09)
### Fixed
[Section titled “Fixed”](#fixed-12)
* **Java visitor API** (#426): `ConversionOptions.builder().withVisitor(...)` now works. The visitor upcall `FunctionDescriptor`s were generated with a `JAVA_LONG` return layout while the `handleVisit*` bridge methods return `int`, so the Java Linker rejected every stub with `IllegalArgumentException: Wrong method handle type: (MemorySegment×5)int` — even a no-op visitor threw before any callback ran. Fixed upstream in the Alef generator (0.34.4); the descriptor return layout is now `JAVA_INT`.
### Changed
[Section titled “Changed”](#changed-10)
* Regenerate all bindings with alef 0.34.4.
* Formatting is now poly-only: removed the `alef:format`, `ruby:format`, and `csharp:format` tasks (which invoked `alef fmt`); `task format` / `poly fmt --fix .` is the single formatter.
## \[3.8.0] - 2026-06-27
[Section titled “\[3.8.0\] - 2026-06-27”](#380---2026-06-27)
Stable release promoting 3.8.0-rc.2 (fully published). Version-only bump synced across all manifests.
## \[3.8.0-rc.2] - 2026-06-27
[Section titled “\[3.8.0-rc.2\] - 2026-06-27”](#380-rc2---2026-06-27)
### Changed
[Section titled “Changed”](#changed-11)
* Regenerate all bindings with alef 0.29.3.
## \[3.8.0-rc.1] - 2026-06-26
[Section titled “\[3.8.0-rc.1\] - 2026-06-26”](#380-rc1---2026-06-26)
### Changed
[Section titled “Changed”](#changed-12)
* **Rebrand Kreuzberg → Xberg across every published package identity.** The Node binding now ships as `@xberg-io/html-to-markdown` (the NAPI-RS crate itself — the separate `-node` package and the TypeScript wrapper under `packages/typescript/` are removed) with platform packages `@xberg-io/html-to-markdown-<platform>`; WASM and CLI move to `@xberg-io/html-to-markdown-wasm` and `@xberg-io/html-to-markdown-cli`. Java/Kotlin Maven coordinates and namespace move to `io.xberg` (`io.xberg:html-to-markdown[-android]`, JNI symbols `Java_io_xberg_android_…`), and the C# NuGet id to `XbergIo.HtmlToMarkdown`. The GitHub org (`github.com/xberg-io`), Homebrew tap (`xberg-io/homebrew-tap`), publisher GitHub App, sponsors links, and all docs/badges follow. The legal entity name **Kreuzberg, Inc.** is unchanged.
### Fixed
[Section titled “Fixed”](#fixed-13)
* **Swift publish now creates the `release/swift/<version>` branch carrying the substituted XCFramework checksum.** The alef-generated Swift e2e/test-app pins `.package(url: …, branch: "release/swift/<version>")`, but the publish workflow only force-moved the `v<version>` tag and never created that branch, so SwiftPM could not resolve the package. The checksummed commit is now also pushed to `refs/heads/release/swift/<version>`. (`.github/workflows/publish.yaml`)
* **test(test_apps/go): extract the module version with `$NF` instead of `$2`.** The smoke harness’ `download_ffi.sh` read the version from `$2`, which only holds in the block `require (…)` go.mod form; the inline `require <path> <version>` form (emitted by the v3.7.2 regen) shifts the version to `$NF`, so the script built a malformed module-cache path and failed with “Binding directory not found”. This is test-harness only — the published Go package is unaffected.
## \[3.7.2] - 2026-06-23
[Section titled “\[3.7.2\] - 2026-06-23”](#372---2026-06-23)
### Fixed
[Section titled “Fixed”](#fixed-14)
* **chore(deps): bump `alef.toml.alef_version` to 0.26.6 and regenerate every binding.** Fixes the dart wrapper crate failing to build under `cargo build --no-default-features`: alef 0.26.x had regressed the 0.25.33 fix and re-emitted `#[cfg(feature = ...)]` on the generated `lib.rs` mirror struct / opaque-wrapper declarations, their `From` conversions, and `from_json` bridge fns, while `frb_generated.rs` references those types/functions unconditionally (`E0425: cannot find type VisitorHandle` / `create_html_metadata_from_json`). alef 0.26.6 keeps those declarations unconditional again. Verified: the regenerated dart crate compiles under `--no-default-features`, default, and `--all-features`. (alef 0.26.6)
* **ci(publish): the Homebrew Swift artifactbundle no longer forces `kreuzberg/openssl-vendored`.** The shared `build-swift-artifactbundle` action hardcoded that feature for its Linux (cargo-zigbuild) targets, but it only exists in the kreuzberg core swift crate — so html-to-markdown’s swift bundle build failed (`the package '…' does not contain this feature`), which cascaded to skip `release-finalize` (and with it the `packages/go/vX.Y.Z` Go module tag). The action now takes a `linux-features` input (left empty here). (shared `xberg-io/actions/build-swift-artifactbundle`)
## \[3.7.1] - 2026-06-23
[Section titled “\[3.7.1\] - 2026-06-23”](#371---2026-06-23)
### Fixed
[Section titled “Fixed”](#fixed-15)
* **ci(homebrew): drop the Intel-macOS `sonoma` bottle from the publish matrix.** The formula intentionally has no `x86_64-apple-darwin` url (Apple-Silicon only), but the bottle matrix still built a `sonoma` (Intel) bottle, which failed with `formula requires at least a URL`. Because `release-finalize` gates on `publish-homebrew-bottles` with `if: !contains(needs.*.result, 'failure')`, that one chronic failure silently **skipped release-finalize for three releases** (v3.6.20, v3.6.21, v3.7.0) — and with it the `packages/go/vX.Y.Z` Go module tag, leaving `go get …/packages/go/v3@vX.Y.Z` unresolvable. Removing the Intel bottle restores release-finalize (and the Go tag) for every future release. (`.github/workflows/publish.yaml`)
* **ci(e2e, C# on Windows): keep `cargo` on PATH in the test before-hook.** The “Run E2E tests (Windows)” step overrode `PATH` via `env:` with `${{ env.PATH }}`, which omits cargo’s `$GITHUB_PATH` additions under Git Bash, so the `cargo build … html-to-markdown-ffi` before-hook failed with `cargo: command not found`. Prepend the target dirs to the live `$PATH` at runtime instead. (`.github/workflows/ci-e2e.yaml`)
* **ci(e2e/docs, Elixir): force the NIF to build from source.** Under `MIX_ENV=test` the `force_build: … or Mix.env() in [:dev]` clause does not apply, so `mix test` tried to download a precompiled NIF for the current (unreleased) version and failed with `the precompiled NIF file does not exist in the checksum file`. Set `RUSTLER_PRECOMPILED_FORCE_BUILD_ALL=1` so the test/doc compile builds the NIF locally. (`scripts/ci/elixir/run-tests.sh`)
* **ci(e2e, Swift): build the FFI crate the generated `Package.swift` links.** The swift e2e before-hook built only `html-to-markdown-rs-swift`, but the generated manifest links `html_to_markdown_ffi`, so `swift test` failed with `library 'html_to_markdown_ffi' not found`. Build `html-to-markdown-ffi` in the before-hook too (matching Go/C#/C). (`alef.toml`)
* **ci(e2e, PHP): drop `--locked` from the PHP test before-hook.** The PHP e2e job’s extension build rewrites the native package deps to the published registry version and runs `cargo update`, mutating the workspace `Cargo.lock`; the subsequent `cargo build --locked -p html-to-markdown-php` then failed with `cannot update the lock file … --locked`. (`alef.toml`)
* **ci(node/wasm): use `--no-frozen-lockfile` for the NAPI binding install.** `build-node-napi` ran a frozen `pnpm install`, but the napi platform packages in `optionalDependencies` are pinned to the unpublished release version and can never be in `pnpm-lock.yaml`, so the install failed with `ERR_PNPM_OUTDATED_LOCKFILE` across every Node build/e2e. (shared `xberg-io/actions/build-node-napi`, `alef.toml`)
* **docs(php): recommend `pie install` over `composer require`.** The PHP package is a native `ext-php-rs` extension that `composer require` cannot load (the cause of #420); every PHP install snippet now leads with `pie install xberg-io/html-to-markdown`. (`docs/`, `readme_templates/`)
### Changed
[Section titled “Changed”](#changed-13)
* **ci(publish): require all 16 PHP PIE cells by explicit per-cell pattern in `verify-release-assets`.** A dropped cell now fails the release instead of silently shipping a partial PIE matrix (#333). (`.github/workflows/publish.yaml`)
* **chore(deps): re-pin `alef.toml.alef_version` to 0.26.5 and regenerate every binding, e2e suite, README, and API doc.** (alef 0.26.5)
## \[3.7.0] - 2026-06-22
[Section titled “\[3.7.0\] - 2026-06-22”](#370---2026-06-22)
### Added
[Section titled “Added”](#added-7)
* **feat(mcp): expand the MCP server to full API parity with typed, discoverable options and complete tool annotations.** The `convert_html` tool now accepts a typed `config` object covering every settable `ConversionOptions` field (heading/list/escaping/whitespace/wrapping, preprocessing, image extraction, output format, tier strategy, …) instead of an opaque untyped JSON blob, so MCP clients discover all options through the tool’s generated `inputSchema`; enum options are accepted as case-insensitive strings parsed by the core parsers. A new `extract_metadata` tool returns structured `<head>`/`<meta>` metadata (title, Open Graph, Twitter Card, JSON-LD/microdata, headers, links, images) as JSON. Both tools carry the full MCP annotation set (`title`, `read_only_hint=true`, `idempotent_hint=true`, `destructive_hint=false`, `open_world_hint=false`). The typed `ConvertConfig` mirror is implemented MCP-side (no changes to the alef-tracked core option types) and guarded by a drift test that fails if a core option is added without being mirrored. The `mcp` feature now implies `metadata`. (`crates/html-to-markdown/src/mcp/`)
* **feat(mcp): add prompts, resources, and completions capabilities.** Beyond tools, the server now advertises three more MCP capabilities: **prompts** — ready-made workflow templates (`convert_to_markdown`, `extract_main_content`, `inspect_metadata`) that drive the tools, with arguments; **resources** — `htmltomarkdown://options-schema` (the JSON Schema of every conversion option) and `htmltomarkdown://output-formats` (the markdown/djot/plain guide); and **completions** — argument autocompletion for prompt arguments (e.g. `output_format` → markdown/djot/plain). (`crates/html-to-markdown/src/mcp/catalog.rs`)
## \[3.6.21] - 2026-06-22
[Section titled “\[3.6.21\] - 2026-06-22”](#3621---2026-06-22)
### Changed
[Section titled “Changed”](#changed-14)
* **chore(deps): re-pin `alef.toml.alef_version` to 0.25.60 and regenerate every binding, e2e suite, README, and API doc.** Folds in the 0.25.59–0.25.60 generator fixes: the R/extendr by-reference DTO rework now emits a non-optional Named param following an optional param as `&T` (passed by reference via an owned `name_core` binding) instead of the non-compiling `Nullable<&T>::into_option()` path; Kotlin/Kotlin-Android content-union `text()` accessors reference the actual data-class payload property (`value`) instead of the non-existent `field0`; generated binding rustdoc de-links core intra-doc references (e.g. ``[`Error::LanguageNotFound`]``) to plain code spans so `rustdoc -D rustdoc::broken-intra-doc-links` passes; and `sync-versions` now runs the same `format_generated` pass as `alef all`, so version-bumped manifests (`package.json`, `composer.json`, `Package.swift`) are byte-identical to the generate path and no longer trip freshness gates. (alef 0.25.60)
# Changelog archive: 3.6.20–3.2.0
## \[3.6.20] - 2026-06-21
[Section titled “\[3.6.20\] - 2026-06-21”](#3620---2026-06-21)
### Fixed
[Section titled “Fixed”](#fixed)
* **chore(precommit): scope the v2.3.0 strict doc/format/lint hooks away from the generated trees.** The canonical-hookset bump (v2.3.0, commit `8a5203b7d`) enabled several strict hooks that ran against alef-generated code and failed on it. All per-language code under `packages/<lang>/`, `e2e/`, and `test_apps/` is generated and ships as alef emits it, so each hook now carries the same generated-tree exclusion the other formatters already use: `yard-coverage` excludes `packages/ruby/` (its `native.rb` holds undocumentable Sorbet-sig RBI defs); `air-check`/`air-format` exclude `packages/` (alef formats R with styler, not air); `palantir-java-format` excludes `packages/`, `e2e/`, `test_apps/`, and the vendored `.mvn/` wrapper. The `lintr` hook runs `lintr::lint_dir(".")` and ignores pre-commit file scoping, so its exclusion lives in a new root `.lintr` (`exclusions: list("e2e", "packages", "test_apps")`); `tsc-typecheck` runs `tsc --noEmit` from the repo root, so a root `tsconfig.json` scopes type-checking to `packages/typescript/src`. `.yardoc/` (yard’s cache side-effect) is gitignored. (`.pre-commit-config.yaml`, `.lintr`, `tsconfig.json`, `.gitignore`)
* **chore(precommit): exclude alef-canonical generated files from the formatters that diverge from alef’s own output.** alef 0.25.58 made `alef verify` output-sensitive and the v2.3.0 hookset added `alef-docs-fresh` (which runs `alef verify`), so any prek formatter that rewrites a generated file differently than alef emits it now breaks verify. Fourteen generated files hit this because the hooks’ pinned tools differ from alef’s: `ruff`/`ruff-format` (line-wrapping generated Python), `pyproject-fmt` (alef runs no pyproject-fmt pass), `oxfmt` (alef formats `composer.json` via npm oxfmt; the hook uses the oxc binary with a different style), `shfmt` (generated `download_ffi.sh`/`install.sh`/`gradlew`), `cargo-sort` (the workspace-excluded R and Elixir NIF `Cargo.toml`), and `end-of-file-fixer` (the Dart `frb_generated.dart` and `test_apps` `__init__.py`). Each now carries the generated-tree exclusion the other tools already use, so the files ship exactly as alef emits them and `alef verify` stays clean. (`.pre-commit-config.yaml`)
### Changed
[Section titled “Changed”](#changed)
* **chore(deps): re-pin `alef.toml.alef_version` to 0.25.58 and regenerate every binding, e2e suite, README, and API doc.** Folds in the 0.25.55–0.25.58 generator fixes that apply here: the generated Go `cmd/download_ffi/main.go` tool now carries the standard `auto-generated by alef` marker so golangci-lint’s `generated: lax` skips it (0.25.x had dropped its `//go:build ignore` guard, exposing inherent-to-a-downloader gosec/errcheck findings); the `generate`/`all` up-to-date skip now also compares against on-disk output (not just the side cache), so out-of-band drift (a `git restore`, a hand-edit, an interrupted write) is regenerated rather than silently retained; **extract** OR-merges cfg gates for same-named types with disjoint gates; **R/extendr** forwards cfg-gated core features into the generated crate’s `[features]` table so it builds under `-D warnings`. The visible churn is the generator’s `.d.ts`/TS-bridge reformatting (tabs→2-space, double→single quotes). Verified locally: `alef verify` is clean and the 3.6.20 bump is synced across all manifests. (alef 0.25.58)
## \[3.6.19] - 2026-06-20
[Section titled “\[3.6.19\] - 2026-06-20”](#3619---2026-06-20)
### Fixed
[Section titled “Fixed”](#fixed-1)
* **test_apps(php): install the PHP extension via PIE’s `pkg:version` syntax.** Both generated PHP test_app installers (`test_apps/php/install.sh`, `test_apps/php_ext/run_tests.sh`) ran `pie install --version "$VERSION" <pkg>`, but PIE parses `--version`/`-V` as “print PIE’s own version” and exits **without installing** — the pinned extension version was never fetched, so the registry-mode PHP smoke validated whatever stale build happened to be present (or nothing). Use `pie install "<pkg>:$VERSION"` so the targeted release is actually installed. (alef 0.25.54)
* **ci(publish): unblock the npm/Node publish under pnpm 11.8.0.** The `node-bindings` job runs `setup-node-workspace` (which installs with `--no-frozen-lockfile`) and then `build-node-napi`, whose own `pnpm install --filter` re-enforces CI’s default frozen-lockfile. The napi platform `optionalDependencies` are pinned to the not-yet-published release version, so they cannot be in the lockfile — pnpm 11.6.0 treated the redundant install as a no-op, but the 11.8.0 bump made it fail (`ERR_PNPM_OUTDATED_LOCKFILE`), dropping every Node build and the npm publish. Pass `install-deps: false` so the already-installed workspace is reused. (`.github/workflows/publish.yaml`)
* **ci(homebrew): drop the macOS-Intel CLI block from the formula template.** The CLI matrix no longer builds `x86_64-apple-darwin` (Apple Silicon only), but `scripts/publish/html-to-markdown.rb.tmpl` + `homebrew.json` still referenced `cli-x86_64-apple-darwin.tar.gz`, so “Update Homebrew formulas” failed (`no assets match the file pattern`) and the tap stayed on the prior version. Remove the macOS `on_intel` block; macOS is now arm-only. (`libhtml-to-markdown` is unchanged — the C FFI still ships an x86_64-apple-darwin archive.)
### Changed
[Section titled “Changed”](#changed-1)
* **chore(deps): re-pin `alef.toml.alef_version` to 0.25.54 and regenerate every binding, e2e suite, README, and API doc.** Folds in the 0.25.51–0.25.54 generator fixes: the PHP PIE `pkg:version` install fix above; **Go** — unit/newtype-tuple enum constants emit serde wire values, a parameter named `result` no longer collides with the codegen variable, and `Option<&[u8]>` returns generate correctly; **R/extendr** — cfg-variant dedup, registration entries drop the stray `#[cfg(...)]`, and opaque-method/`Option`/`Vec`/error returns convert properly; **C#** — corrected host-capsule native method name; **Swift** — `Package.swift` dependency argument order and e2e `harness_extras` product override; **test_apps runner** — declared `[crates.e2e.env]` vars are exported to the run command. Verified locally: both PIE fixes are present in the regenerated test_apps and the 3.6.19 bump is synced across all manifests.
* **chore(precommit): scope `oxfmt`/`oxlint` away from generated `e2e/`+`test_apps/`.** alef has no e2e/test_apps JS/TS formatter (`alef.toml [crates.e2e.format]` covers go/python/rust/c only), so `oxfmt` was the lone tool reformatting generated test JS, producing churn on every regenerate. Add the `^(e2e/|test_apps/)` exclude that `go-fmt`, `ruff-format`, and `golangci-lint` already carry; generated test JS now ships as alef emits it, matching `e2e/ruby`, `e2e/php`, etc. (`.pre-commit-config.yaml`)
## \[3.6.18] - 2026-06-20
[Section titled “\[3.6.18\] - 2026-06-20”](#3618---2026-06-20)
### Fixed
[Section titled “Fixed”](#fixed-2)
* **ci(publish): unbreak Python wheels on every platform.** The shared `build-python-wheels` action source-built libheif 1.23.0 (with `libde265`/`x265` codec headers) for *all* consumers because kreuzberg links `libheif-sys`. html-to-markdown does not use libheif, but inherited the build — which fails on the `manylinux2014` (CentOS 7 EOL) base whose yum repos no longer carry `libde265-devel`/`x265-devel` (`Error: Not tolerating missing names on install`). The action now gates the libheif build behind an opt-in `build-libheif` input (default off); h2m no longer builds it, so all Python wheels build again. (`xberg-io/actions@v1`)
* **ci(publish): re-exclude `php8.5` + `macos-arm64`, restoring PHP publishing.** v3.6.17 tried to build the php8.5 Apple-Silicon PIE asset on the `macos-14` runner ([#333](https://github.com/xberg-io/html-to-markdown/issues/333)), but `shivammathur/setup-php` cannot provision PHP 8.5 on arm64 on *any* macOS runner (the install leaves empty paths — `sed: : No such file`, `/php.ini: No such file`). That failing cell skipped `upload-php-pie-release`, dropping **every** PHP PIE asset (a v3.6.15-class regression). Restoring the exclusion republishes the PHP extension for all supported targets (PHP 8.2–8.5 on linux/macos-x86_64/windows, plus arm64-darwin for 8.2–8.4). #333 stays open pending an upstream php\@8.5 arm64 formula. (`.github/workflows/publish.yaml`)
### Changed
[Section titled “Changed”](#changed-2)
* **chore(deps): re-pin `alef.toml.alef_version` to 0.25.50 and regenerate every binding, e2e suite, README, and API doc.** Folds in the 0.25.50 cross-language visitor-codegen fixes that turn the chronically-red e2e visitor suites green: **Node** — the bridge now reads the externally-tagged `{ Custom: ... }`/`{ Error: ... }` payload key (was lowercased to `custom`/`error`, yielding `[object Object]`); **Ruby** — visitor callbacks take named params and interpolate `{placeholder}` templates; **PHP** — bare-string returns map to `Custom` for multi-payload result enums; **Elixir** — unit-variant atoms match the snake_case wire name (`:skip` no longer leaks as literal `"Skip"`); **Swift** — `visitBlockquote`’s `depth` is `UInt`, so the override satisfies the protocol. Verified locally: every language e2e suite passes and `alef verify` is clean.
## \[3.6.17] - 2026-06-19
[Section titled “\[3.6.17\] - 2026-06-19”](#3617---2026-06-19)
### Fixed
[Section titled “Fixed”](#fixed-3)
* **ci(publish): stage Java natives under the `macos-*` RID the loader expects, fixing Java on all macOS.** The `java-natives` matrix labelled the macOS cells `osx-aarch64` / `osx-x86_64`, which became the `natives/<rid>/` directory baked into the jar, but the loader (`NativeLib.resolveNativesRid`, alef `go_java_platform`) expects `macos-arm64` / `macos-x86_64`. The published jar therefore failed with `UnsatisfiedLinkError` on every macOS. Align the labels with the loader. (`.github/workflows/publish.yaml`)
* **ci(publish): bundle the Dart native libraries into the published package.** `assemble-dart-package` shipped the pub.dev tarball with no native libraries, so the loader fell back to a relative framework path that hardened runtimes reject — the package was unusable for every consumer. Add a `dart-natives` matrix that builds the `html-to-markdown-rs-dart` cdylib per platform and stages it into `lib/src/native/<rid>/` where the loader (`_alefHostRid`) looks. (`.github/workflows/publish.yaml`)
* **ci(publish): build the PHP 8.5 macOS-arm64 extension on the `macos-14` runner ([#333](https://github.com/xberg-io/html-to-markdown/issues/333)).** `shivammathur/setup-php` only provisions PHP 8.5 on Apple Silicon via the `macos-14` runner, not `macos-latest` (15/26). The `php-extension` matrix used `macos-latest` and excluded php8.5/macos-arm64, so that PIE asset was never built. Build the macos-arm64 cell on `macos-14` and drop the exclusion so the `php8.5-arm64-darwin` PIE asset ships. (`.github/workflows/publish.yaml`)
* **fix(task): refresh `go.sum` in the Go smoke test.** `test-apps:smoke:go` failed with “missing go.sum entry” after a version bump because alef edits `go.mod` only. Run the targeted `go mod download <module>` Go suggests — it adds the entry without rewriting `go.mod`’s block form, which `download_ffi.sh` parses for the version. (`Taskfile.yaml`)
* **test(ci): run the Java e2e step on macOS to cover native RID resolution.** The Java e2e ran the e2e step only on ubuntu, so macOS-specific binding/native regressions (such as the RID mismatch above) were never exercised. Run it on macOS too. (`.github/workflows/ci-e2e.yaml`)
### Changed
[Section titled “Changed”](#changed-3)
* **chore(deps): re-pin `alef.toml.alef_version` to 0.25.49 and regenerate every binding, e2e suite, README, and API doc.** Folds in the 0.25.45–0.25.49 generator fixes (incl. kotlin-android AGP 9 toolchain, swift bridge build, content-union accessors). Verified locally: `alef verify` is clean and `task alef:format` succeeds across all languages.
* **chore(precommit,alef): standardize kotlin-android formatting on ktfmt `--kotlinlang-style`.** Drop the conflicting prek `ktlint` hook (its always-format mode fought `ktfmt` over blank-line-after-brace and rewrote alef’s `///` doc comments to `// /`, breaking `alef verify`), switch `alef.toml` kotlin-android format/check from gradle-`ktlintFormat` to `ktfmt` so alef and prek agree, and exclude the vendored Gradle wrapper from shellcheck. detekt remains for static analysis. (`.pre-commit-config.yaml`, `alef.toml`)
* **chore(alef): close formatter-coverage gaps for generated Go and Zig.** Add a `gofmt -w` format hook for `packages/go`/`e2e/go` (alef’s Go emitter output needs canonical re-indentation), and extend the Zig formatter/check to cover `build.zig` in addition to `src`. (`alef.toml`)
## \[3.6.16] - 2026-06-19
[Section titled “\[3.6.16\] - 2026-06-19”](#3616---2026-06-19)
### Fixed
[Section titled “Fixed”](#fixed-4)
* **ci(publish): re-exclude `php8.5` + `macos-arm64` from the PHP extension matrix, restoring PHP publishing.** v3.6.15 removed this exclusion to chase the Apple-Silicon PIE asset for [#333](https://github.com/xberg-io/html-to-markdown/issues/333), but `shivammathur/setup-php` still cannot provision PHP 8.5 on `macos-arm64` — the homebrew tap has no `php@8.5` arm64 formula, so the cell fails at the setup step with “Could not setup PHP 8.5”. Because `upload-php-pie-release` does not run when `needs.php-extension.result == 'failure'`, that single failing cell dropped **every** PHP PIE asset from the v3.6.15 release (a regression from v3.6.14’s full set). Restoring the exclusion returns the matrix to all-green and republishes the PHP extension for every supported target (PHP 8.2–8.5 on linux/macos-x86_64/windows, plus arm64-darwin for 8.2–8.4). #333 stays open until upstream ships a `php@8.5` arm64 formula. (`.github/workflows/publish.yaml`)
* **ci(publish): re-publish the Ruby gems missing from v3.6.15.** The v3.6.15 run skipped `publish-rubygems` because the `Build Ruby gem (windows-x64)` cell hung \~3h on `setup-rust` and was cancelled, failing the `needs.ruby-gem.result == 'success'` gate. This is a transient runner fault, not a code defect; cutting v3.6.16 re-runs the publish so the gems ship.
## \[3.6.15] - 2026-06-18
[Section titled “\[3.6.15\] - 2026-06-18”](#3615---2026-06-18)
### Fixed
[Section titled “Fixed”](#fixed-5)
* **ci(publish): attempted to build the PHP 8.5 + macOS arm64 (Apple Silicon) PIE extension ([#333](https://github.com/xberg-io/html-to-markdown/issues/333)) — ineffective, reverted in 3.6.16.** Removed the build-matrix exclusion for `php8.5` on `macos-latest`, but `shivammathur/setup-php` cannot install PHP 8.5 on arm64 (no `php@8.5` arm64 homebrew formula), so the cell failed at setup and — because `upload-php-pie-release` skips on a failed matrix — dropped all PHP PIE assets from this release. See the 3.6.16 entry. (`.github/workflows/publish.yaml`)
* **docs(php): use the native `HtmlToMarkdownApi` class in all PHP examples.** The README quick-start, API reference, and docs snippets used the `HtmlToMarkdown` userland wrapper, which is only autoloaded via Composer’s PSR-4 and is absent on the PIE install path (extension-only) — so `HtmlToMarkdown::convert()` raised “Class not found” for users who installed via `pie`. Examples now call `HtmlToMarkdownApi::convert()`, the native class registered by the extension itself, which works on both the PIE and Composer install paths ([#415](https://github.com/xberg-io/html-to-markdown/issues/415)). (`readme_templates/partials/`, `docs/snippets/php/`, `docs/language-guides.md`)
### Changed
[Section titled “Changed”](#changed-4)
* **chore(deps): bump `alef.toml.alef_version` to 0.25.44 (was 0.25.40) and regenerate every binding, e2e suite, README, and API doc.** Folds in the 0.25.41–0.25.44 cross-language generator fixes. Verified locally: `alef verify` is clean, `cargo check --workspace --all-features` compiles, and `prek run --all-files` (including the alef freshness hook) passes.
## \[3.6.14] - 2026-06-18
[Section titled “\[3.6.14\] - 2026-06-18”](#3614---2026-06-18)
### Fixed
[Section titled “Fixed”](#fixed-6)
* **chore(deps): bump `alef.toml.alef_version` to 0.25.40 (was 0.25.36) and regenerate every binding.** Advances the pin past the `[Unreleased]` 0.25.33 note to a tagged, published alef revision and folds in the 0.25.34–0.25.40 cross-language fixes. Binding-visible changes: **Java** drops the throwing `UnsupportedOperationException` DTO/enum-method stubs (`NodeContext.withOwnedAttributes`/`intoOwned`, `ConversionOptions.defaultInstance`, `PreprocessingOptions.defaultInstance`) — there is no JNI symbol for these yet, so the stubs compiled but threw at runtime; absence is safer than a misleading throw until DTO marshaling lands (boxed-`Boolean` serde defaults also restored). **Swift** emits a matching `pub fn visitor_handle_noop` definition for the bridge no-op declaration so the swift rust crate compiles (was `E0425` under 0.25.36’s decl-without-def), alongside the upstream streaming-owner declaration rework. **Node (NAPI)** map-returning functions now convert borrowed maps to owned `HashMap` instead of returning them bare (fixes a would-be `E0308` from the new DTO-method emission). **Python (pyo3)** drops a redundant `# type: ignore[arg-type]` on the visitor assignment that `mypy --strict` (`warn_unused_ignores`) rejected, and None-guards the coercion comprehension for optional `Vec<enum>` fields. Verified locally: `task alef:generate` is fresh (`alef verify`), every workspace binding crate compiles, and `prek run --all-files` is clean.
* **ci(publish): `upload-php-pie-release` now hard-errors if zero `php-package-*` artifacts reach the aggregator instead of producing an empty PIE upload.** The download step adds `if-no-files-found: error`, so a future regression that drops all PHP build outputs surfaces immediately instead of silently shipping a release with no PIE assets — the failure mode behind v3.6.11’s missing-asset reports (see [#333](https://github.com/xberg-io/html-to-markdown/issues/333)). The matrix-cell tolerance from v3.6.12 (`needs.php-extension.result != 'cancelled' && != 'skipped'`) is unchanged. (`.github/workflows/publish.yaml`)
* **ci(task rust:test): re-include `html-to-markdown-rs-dart` in the `--no-default-features --workspace` sweep.** The provisional exclusion added earlier in this `[Unreleased]` cycle is now unnecessary: alef 0.25.33 + the queued `[Unreleased]` follow-up drop `#[cfg(feature = ...)]` from every dart-wrapper mirror declaration **and** the bidirectional `From` impls, so the wrapper crate compiles cleanly under default, `--no-default-features`, and `--all-features`. Verified locally against a fresh `task alef:generate`. (`.task/languages/rust.yml`)
* **chore(deps): bump `alef.toml.alef_version` to 0.25.33 and regenerate every binding.** Sweeps in the cross-language fixes accumulated through 0.25.30–0.25.33 plus the (still-`[Unreleased]`) dart cfg follow-up that the regen incorporates locally: pyo3 `convert(...)` / `ConversionOptions(__init__)` visitor kwarg widened to `HtmlVisitor | object | None` (resolves [#403](https://github.com/xberg-io/html-to-markdown/issues/403)); swift options-field factory exported as `make{Trait}Handle` (matches docs snippets + e2e generator); java record + builder PMD cleanup (per-instance non-`final` fields, redundant component docs removed); kotlin file-level `@file:Suppress` extended with `ReturnCount` + `NestedBlockDepth` on the shared emitter; codegen `Vec<core::T>` → `Vec<wrapper::T>` conversion on non-opaque method returns (pyo3, magnus, extendr); wasm `Option<Vec<UnitEnum>>` getter/setter emission; php untagged-data-enum delegation via `serde_json::from_value`; extract honors `#[cfg_attr(alef, alef(skip))]` on `impl` blocks (no more duplicate `#[no_mangle]` symbols on builder + field name collisions); cfg-gated public function re-exports treated as binding surface; extendr `extendr_module!` registration entries gated on the source `FunctionDef` cfg; dart mirror enum + struct declarations + bidirectional `From` impls all unconditional now so `frb_generated.rs` resolves against the local crate regardless of the dart wrapper’s feature set. Pin will advance again to a tagged alef revision once the `[Unreleased]` dart follow-up + extendr fix ship in 0.25.34.
## \[3.6.13] - 2026-06-17
[Section titled “\[3.6.13\] - 2026-06-17”](#3613---2026-06-17)
### Fixed
[Section titled “Fixed”](#fixed-7)
* **style(test_apps/go): `shfmt`-normalize `download_ffi.sh` so CI Lint’s `shfmt` hook stops rejecting the v3.6.12 baseline.** The hand-written cgo library stager shipped with v3.6.12 used inline case-arm bodies; CI’s `shfmt -i 2 -ci -bn -s` profile splits them onto separate lines. CI Lint failed on every v3.6.12 commit until the file was normalized.
* **(via alef 0.25.26–0.25.28)** Generated bindings pick up: PHP shared lossy and enum-tainted binding-to-core helpers now skip `binding_excluded` fields and emit `..Default::default()` so core types with custom `Default` impls (e.g. anything that pulls config from the environment) are no longer shadowed by zeroed field defaults across Python/Node/Ruby/WASM/extendr/PHP method bodies and From-impls; FFI same-name function dedup moved out of the shared extractor pass into a backend-local pass (`backends::ffi::gen_bindings::functions::cfg_dedup::dedup_same_name_functions`) so every other backend and the e2e call-export validator see the original multi-entry surface untouched (v0.25.26 had over-collapsed the shared surface and stripped `alef(skip)`-tagged siblings from every backend); FRB Dart bridge functions wrapping core functions that return primitives now emit the cross-type cast (e.g. `.map(|v| v as i64)`) instead of the redundant `.map(|v| v)` that v0.25.25–0.25.27 emitted; generated Kotlin Android files add `ReturnCount` to the `@file:Suppress` list so detekt no longer fails sealed-class deserializers with 3+ variants.
* **(via alef 0.25.27)** Generated Swift bindings emit the factory function as `make{Trait}Handle` (matching the documented spec, the docs snippets under `docs/snippets/swift/visitor/`, and the e2e test generator) instead of `make{Trait}{TypeAlias}` (which silently doubled the trait stem to `makeHtmlVisitorVisitorHandle`); generated Swift e2e visitor closures qualify the context type with the host module (`HtmlToMarkdown.NodeContext`) so the unqualified reference is no longer ambiguous against `RustBridge.NodeContext` that the test file also imports.
* **(via alef 0.25.27)** Generated TypeScript WASM e2e configs override `SsrfPolicy.denyPrivate = false` when the binding exposes the field, since WASM has no `std::env::var` and `SsrfPolicy::from_env()` always falls back to `deny_private = true`, which rejected the localhost mock-server requests every WASM e2e fixture targets.
### Changed
[Section titled “Changed”](#changed-5)
* **Bump alef pin to 0.25.28** (was 0.25.25), regenerating all binding outputs, e2e codegen, API reference docs, and test_apps scaffolds.
## \[3.6.12] - 2026-06-17
[Section titled “\[3.6.12\] - 2026-06-17”](#3612---2026-06-17)
### Fixed
[Section titled “Fixed”](#fixed-8)
* **test_apps/go: stage cgo FFI library into the binding’s module-cache `.lib/<platform>/` so smoke tests link cleanly.** The published Go binding declares `// #cgo LDFLAGS: -L${SRCDIR}/.lib/<platform>/ -lhtml_to_markdown_ffi`, but `${SRCDIR}` resolves to the binding’s source directory under `GOMODCACHE`, which is empty after `go mod download`. The package’s own `cmd/download_ffi` is `//go:build ignore`-tagged and only invocable via the binding’s own `go generate`, which test_apps doesn’t run. Fix: `test_apps/go/download_ffi.sh` reads `MODULE_VERSION` from `go.mod`, downloads the matching `html-to-markdown-rs-ffi-v<version>-<rust-triple>.tar.gz` artifact from the GitHub release, caches it under `${XDG_CACHE_HOME:-~/.cache}/html-to-markdown-ffi/`, makes the binding’s module-cache subtree writable, and copies the library into `<binding>/.lib/<platform>/`. The smoke task invokes the script before `go test`. Restores Go to the registry-mode smoke matrix.
* **ci(publish): replace single-success gate on `upload-php-pie-release` with cancelled/skipped guards so partial matrix success still publishes the available PIE archives.** The job was gated on `needs.php-extension.result == 'success'`, which meant a single transient matrix-cell failure (e.g. the `ENOTFOUND` artifact-upload flake observed on the v3.6.11 publish run) cascaded into skipping the entire PIE upload step. With the matrix already declared `fail-fast: false` and the in-job `actions/download-artifact@v4` step configured with `pattern: php-package-*` + `merge-multiple: true`, the upload now proceeds whenever at least one matrix cell produced an artifact. Transient flakes no longer block the entire release surface.
* **(via alef 0.25.20–0.25.25)** Generated binding suites pick up: NAPI TypeScript `import { A as B }` → CJS `{ A: B }` rename translation (so `oxfmt` no longer aborts on `Expected ',' or '}' but found 'as'`); Go FFI `copyLibraryToBindingPackage` no-op when source aliases destination (avoids 0-byte `libhtml_to_markdown_ffi.dylib` after `go generate`); Swift `Package.swift` `v__ALEF_SWIFT_VERSION__` placeholder substitution at scaffold-write time so SwiftPM consumers don’t 404 against the release asset URL; Homebrew `run_tests.sh` formula-installed CLI preflight using the parameterized binary name; alef post-generation formatter pipeline aligned with downstream prek hooks (`ktfmt` for Kotlin format, `gofmt`+`goimports` for Go, `oxfmt` for TS/JSON, `shfmt` for shell scripts, `php-cs-fixer` for PHP, `cargo sort` for emitted Cargo.toml). Resolves CI Lint formatter divergence that had been red on every commit since v3.6.11.
* **(via alef 0.25.25)** Generated PHP test_apps `install.sh` emits `pie install --version "$VERSION" "<pkg>"` instead of the deprecated `pie install "<pkg>:$VERSION"` form that PIE 1.4.5+ rejects with `Unable to find an installable package <pkg> for version <ver>`. Restores PHP to the registry-mode smoke matrix.
* **(via alef 0.25.25)** Generated `[crates.dart] excluded_default_features` / `[crates.swift] excluded_default_features` keep optional cargo features out of the wrapper’s `default = [...]` array while still declaring them as opt-in forwarding entries, preventing target-conditional cross-compile activation of features whose system deps aren’t cross-compile-ready.
* **(via alef 0.25.25)** Generated publish/vendor flow retries `cargo update` + `cargo metadata` on crates.io registry-index propagation lag (up to 6 attempts × 30 s) so per-language build jobs don’t hard-fail in the first few minutes after `Publish Rust crates` completes.
### Changed
[Section titled “Changed”](#changed-6)
* **Bump alef pin to 0.25.25** (was 0.25.19), regenerating all binding outputs, e2e codegen, API reference docs, and test_apps scaffolds.
## \[3.6.11] - 2026-06-16
[Section titled “\[3.6.11\] - 2026-06-16”](#3611---2026-06-16)
### Fixed
[Section titled “Fixed”](#fixed-9)
* **Table layout pre-pass: skip nested-table rendering during column-width measurement (issue #406, residual fix).** The `MAX_CELL_WIDTH = 200` cap shipped in v3.6.10 (`4013a6864`) bounded the discarded *output* but not the measurement CPU. For deeply nested layout HTML (e.g. the reporter’s Outlook digest: 393 `<table>` tags, 851 KB), `cell_text_content` still recursively dispatched `handle_table_with_context` on every nested table during the outer measurement pre-pass, triggering its own pre-pass on every descendant cell — combinatorial explosion (`cells × nested_cells × ...`) unbounded at greater nesting depth. The reproducer still ran for tens of minutes on v3.6.10. The fix threads `measure_width_only: bool` through the conversion `Context`; `walk_node`’s `"table"` arm short-circuits to descendant text content when set, keeping the pre-pass linear in descendant character count. The reproducer now converts in 0.04 s. Regression test `nested_layout_tables_convert_within_wall_clock_budget` covers a synthetic 4×4 nested-cell fixture with a 10s wall-clock budget. Tier-1 vs Tier-2 separator-row dash counts now diverge on the nested-table fallback (Tier-1 still measures the rendered cell text); existing tier-divergence tests were updated to assert outer-row content equality instead of byte-equality. Resolves the residual #406 report from `hobofan` on 2026-06-16.
* **(via alef 0.25.19)** Generated Swift app harness migrates fixtures JSON from triple-quote multi-line string literal to chunked-array `[...].joined()`, avoiding Swift’s `multi-line string literal content must begin on a new line` error when the Jinja whitespace-trim placed content on the same line as the opening `"""`.
* **(via alef 0.25.19)** Generated FFI service-API codegen clones borrowed opaque-pointer params at the call site so consuming Rust APIs that take `T` by value receive an owned value while the C caller retains the original handle for its own `_free` call.
* **(via alef 0.25.19)** Generated csharp e2e csproj template branches `<RuntimeIdentifier>` on `OSArchitecture`, picking `osx-arm64` / `linux-arm64` / `win-arm64` on arm64 runners instead of hardcoded `*-x64`.
* **(via alef 0.25.19)** Generated magnus binding `Cargo.toml` emits a cfg-feature forwarding `[features]` block so any `#[cfg(feature = "X")]` arms in the binding compile under `-D warnings`.
### Added
[Section titled “Added”](#added)
* **(via alef 0.25.19)** Generated language doc pages translate Rust type spellings to language-native terminology in prose (Python `list[X]` / `dict`, TypeScript `X[]` / `Record`, Go `[]X` / `map`, etc.), applied via `map_non_code_lines` so code fences stay intact.
## \[3.6.10] - 2026-06-16
[Section titled “\[3.6.10\] - 2026-06-16”](#3610---2026-06-16)
### Fixed
[Section titled “Fixed”](#fixed-10)
* **Table column-width: cap per-cell measurement at 200 characters (issue #406).** Converting Microsoft-style HTML emails with hundreds of nested layout tables produced runaway output (73 MB / 2.2 s for the reporter’s 851 KB reproducer) because `collect_row_cell_widths` used the *rendered* width of each cell — including any inner table’s separator rows — as the outer column width. The outer table’s separator was then emitted with that many dashes, which fed back into the grandparent’s measurement, doubling at every nesting level. Capping the per-cell measurement at `MAX_CELL_WIDTH = 200` bounds total output to `O(cells × 200)` and keeps both the Tier-1 fast path and the Tier-2 walker numerically consistent. The reproducer now converts in 0.47 s producing 218 KB of markdown. Bisected by the reporter to alef-driven `Arc<Mutex<>>` visitor migration in 3.4.1 (`7f6178f25`); the v3.6 series already fixed the visitor-mutex hot loop in `4863d1ab6`, but the underlying exponential-width feedback remained. Regression test added: `deeply_nested_layout_tables_do_not_produce_runaway_output`.
* **Bump alef to 0.25.18.** Picks up: (a) the **e2e visitor codegen fixes** for Node and C# — Node tests now pass `{ visitor: V as any }` through `options.visitor` rather than as a silently-dropped third positional argument, C# tests merge into the existing `new ConversionOptions()` literal rather than appending a fourth arg, restoring every `Custom`-substitution visitor test. (b) The **Zig e2e build.zig fix** dropping the duplicated `_run` suffix in test-sequencing `dependOn` calls (`conversion_run_run` → `conversion_run`), unblocking Test: Zig. (c) The **Swift box-delegate cast fix** removing the spurious `Int(...)` wrap on `usize`/`isize` args so the bridge call matches the `UInt` protocol declaration, unblocking Test: Swift. (d) The **Ruby Rakefile modifier-`if` fix** for `cross_compile_versions` assignment, removing the `Style/IfUnlessModifier` rubocop offense that broke all 4 Test: Ruby matrix jobs. (e) The **PHP PIE URL `{OSLower}` placeholder fix** so `pie install xberg-io/html-to-markdown` resolves the correct asset name (resolves h2m #333). (f) The **binding-crate feature passthrough block** emission in FFI/Node/PHP/Wasm `Cargo.toml` — each binding crate now declares `metadata`, `visitor`, `inline-images`, `testkit` as passthrough features forwarding to `html-to-markdown-rs/X`, fixing the `unexpected cfg condition value` errors under `RUSTFLAGS="-D warnings"` for code paths gated by core features. (g) The **swift-bridge owner-type extern block + cfg-gating fix** preventing proc-macro expansion failures on cfg-disabled types. (h) The **JNI trait-`use` emission fix** so Tier-B Rust-public trait extension points are reachable from the generated JNI shims.
## \[3.6.9] - 2026-06-15
[Section titled “\[3.6.9\] - 2026-06-15”](#369---2026-06-15)
### Fixed
[Section titled “Fixed”](#fixed-11)
* **Bump alef to 0.25.17.** Picks up the dart `unreachable_patterns` allow attribute for the crate-root, which was missing from the dart `gen_rust_crate` scaffold. v3.6.8’s CI Rust failed with `unreachable pattern` errors at `packages/dart/rust/src/lib.rs:1739` and `:2102`: the dart enum-conversion path emits an `_ => unreachable!("cfg-gated variant ... not active in this build")` catch-all so the match remains exhaustive when a `#[cfg(feature = "X")]`-gated variant is compiled out, but the dart binding’s `[features]` table forwards `testkit` unconditionally, so the cfg-gated arm IS compiled in and the catch-all is unreachable — `-D warnings` turned the lint into an error. alef 0.25.17 adds `unreachable_patterns` to the existing `#![allow(unused_variables, unreachable_code)]` crate-root attribute, matching the swift backend’s already-correct allow list.
## \[3.6.8] - 2026-06-15
[Section titled “\[3.6.8\] - 2026-06-15”](#368---2026-06-15)
### Fixed
[Section titled “Fixed”](#fixed-12)
* **Bump alef to 0.25.16.** Picks up the vendor `manifest_abs` canonicalize fix (resolves Elixir NIF / PHP extension / Ruby gem / Python sdist `alef publish prepare` failures from the v3.6.7 publish run), the Dart `cfg(testkit)` whitespace fix (unblocks `Validate: Rust` and `Test: Dart` on main), the rustler `.clone()` skip for reference parameters, the JNI workspace-target host fix, the extendr enum type-path resolver, the swift `From<core>` cfg-gating for variant arms, the FFI visitor enum-context i32 emission, the visitor_result bare-string `Custom` routing, the e2e csharp SDK-AssemblyInfo suppression, prerelease set-version support (0.25.10–11); the swift cfg-union postprocessing fixes for default-build wrapper-type emission and the `default = [<features>]` Cargo.toml emission (0.25.12–15); and the drop of cfg propagation on enum `From`-impl match arms — binding crates do not declare gated features themselves but pull the core dependency with them enabled, so propagating `#[cfg(feature = "testkit")]` to binding-side arms produced `unexpected cfg condition value: testkit` errors under `-D warnings` on py/node bindings (0.25.16).
* **C# assembly identity now tracks `<Version>`.** Deleted the hand-committed `packages/csharp/HtmlToMarkdown/Properties/AssemblyInfo.cs` (carrying a stale `AssemblyVersion("3.4.0")`) and switched the scaffold to let the .NET SDK derive `AssemblyVersion`, `AssemblyFileVersion`, and `AssemblyInformationalVersion` from `<Version>` plus the new `<Company>` / `<Product>` MSBuild properties. The published 3.4.0 assembly identity was breaking `task test-apps:smoke:csharp` against every NuGet package since the original ship.
### Changed
[Section titled “Changed”](#changed-7)
* **CI E2E PHP/Ruby builds: re-enable `rewrite-native-deps`.** The workaround in 3.6.7 (`a8c7fe40c`) disabled `rewrite-native-deps` on PHP and Ruby `build-*` actions to dodge the alef 0.25.9 canonicalize bug. With 0.25.11’s fix the action works correctly again, so the four `rewrite-native-deps: "false"` overrides are removed.
## \[3.6.7] - 2026-06-15
[Section titled “\[3.6.7\] - 2026-06-15”](#367---2026-06-15)
### Fixed
[Section titled “Fixed”](#fixed-13)
* **Restore Dart binding.** v3.6.6 silently dropped Dart from `[workspace].languages` in `alef.toml` and moved `packages/dart/rust` from workspace `members` to `exclude` in the root `Cargo.toml`. The pub.dev publish of `h2m` 3.6.6 succeeded only because the Dart workflow’s tag-time checkout predated the exclusion; any subsequent regeneration would have orphaned the binding. Dart is restored to both lists.
* **Bump alef to 0.25.9 — fixes Elixir NIF `[patch.crates-io]` no-op error blocking the v3.6.6 publish.** alef 0.25.7’s Elixir scaffold emitted an unconditional `[patch.crates-io]` block in the generated Rustler NIF `Cargo.toml` with entries shaped `alloc-no-stdlib = { version = "=2.0.4" }` — cargo rejects these as `patch for 'alloc-no-stdlib' points to the same source, but patches must point to different sources`, failing every Elixir NIF matrix cell (linux x86_64/aarch64, macos x86_64/arm64) plus the Hex publish job on v3.6.6 publish run 27510348278. alef 0.25.9 (commit `e1e86bbc1`) replaces the broken patch block with direct `[dependencies]` entries pinning `alloc-no-stdlib = "=2.0.4"`, `alloc-stdlib = "=0.2.2"`, `brotli-decompressor = "=5.0.1"` plus matching `cargo-machete` ignores. 0.25.9 also ships the Ruby Rakefile YARD-coverage fix (`55f1eccf6`).
## \[3.6.6] - 2026-06-14
[Section titled “\[3.6.6\] - 2026-06-14”](#366---2026-06-14)
### Fixed
[Section titled “Fixed”](#fixed-14)
* **Bump alef to 0.25.7 — fixes `alef publish prepare` for non-workspace-member NIF crates (Ruby gem, Elixir NIF).** alef 0.25.4–0.25.6 had a bug where `cargo update --locked` and `cargo metadata --locked` would fail for binding crates that are not workspace members (like the Rustler NIF and Magnus gem). The seed lockfile lacked a `[[package]]` entry for the binding crate, causing cargo to reject it. alef 0.25.7 dropped `--locked` from the metadata validation step and set `.env_remove("CARGO_BUILD_LOCKED")` to allow cargo to resolve these crates from the registry. This fix restores Ruby (all platforms) and Elixir NIF (all platforms + Hex package) support.
## \[3.6.5] - 2026-06-14
[Section titled “\[3.6.5\] - 2026-06-14”](#365---2026-06-14)
### Fixed
[Section titled “Fixed”](#fixed-15)
* **Elixir Hex/NIF + Ruby gem publish: bump alef pin to 0.25.4 so `alef publish prepare` produces a valid binding lockfile.** alef 0.25.1’s `vendor::scrub_or_regenerate_lock` strict-mode path failed on every v3.6.4 Elixir NIF and macOS/Linux Ruby gem build with `cargo update -p <lockfile> (or final cargo metadata validation) failed (exit code 101) ... cannot update the lock file ... because --locked was passed` — the seed lockfile’s workspace-member path entries collided with the registry-source entries the rewrite added, and the final `cargo metadata --locked` validation could not reconcile them. alef 0.25.3 added `strip_workspace_member_entries` to drop the path-source entries from the seed before per-member `cargo update -p` runs, plus a full registry-URL package-id spec (`registry+https://github.com/rust-lang/crates.io-index#NAME@VERSION`) to disambiguate the per-member update. 0.25.4 also escapes Rust reserved keywords in extendr struct fields (relevant to R bindings consuming flat data enums with `serde(tag = "type")`).
* **Python sdist on Alpine/musl: `actions/rewrite-native-deps` v1.8.69 now strips `path = "..."` from `[workspace.dependencies]` entries.** The 3.6.4 sdist’s root `Cargo.toml` shipped with `[workspace.dependencies] html-to-markdown-rs = { version = "3.6.4", path = "crates/html-to-markdown" }`, and cargo eagerly validates every workspace-dep entry on `pip install` — bailing with `failed to read .../crates/html-to-markdown/Cargo.toml` because the workspace crate is not bundled in the sdist. v1.8.66 added `[patch.*]` stripping for sdist consumers (resolved #390) but missed `[workspace.dependencies]`. The new step drops `path` from every workspace-dependency entry, leaving the version so the dep resolves from crates.io on consumer install. Resolves #402.
## \[3.6.4] - 2026-06-14
[Section titled “\[3.6.4\] - 2026-06-14”](#364---2026-06-14)
### Fixed
[Section titled “Fixed”](#fixed-16)
* **CLI: drop `reqwest` `brotli` feature to keep `alloc-no-stdlib` on 2.x.** The transitive `brotli` crate (pulled in via `async-compression`) jumped to 8.x which expects `alloc-no-stdlib` 3.x, but the workspace resolves the sibling at 2.x. The resulting trait drift broke `cargo build` on stable rustc with `the trait bound 'StandardAlloc: alloc::Allocator<...>' is not satisfied`, blocking the ubuntu-latest Python wheel build during the v3.6.3 publish run. The CLI’s HTTP client now uses gzip+deflate only.
* **Publish workflow: dispatch `publish-pubdev` with the release tag, not the branch ref.** When `publish.yaml` was triggered by `release: published`, `github.ref_name` resolved to the branch where the release was authored (e.g. `main`). The child workflow’s OIDC token then carried `refType=branch`, which pub.dev rejects with `publishing is only allowed from 'tag' refType`. Dispatch now uses `needs.prepare.outputs.tag` so the child runs against the tag and the OIDC token is accepted.
* **Taskfile: `test-apps:test:zig` now grep’d the root `Cargo.toml` for the workspace version.** The previous grep targeted `crates/html-to-markdown/Cargo.toml`, which uses `version.workspace = true` and has no literal version line — `H2M_VERSION` resolved to empty and the zig-fetch URL collapsed to `…/download/v/html-to-markdown-rs-zig-v.tar.gz` (404).
### Changed
[Section titled “Changed”](#changed-8)
* **Track `Cargo.lock` for reproducible builds.** `Cargo.lock` was previously gitignored, defeating `cargo build --locked` everywhere it was used. Every CI runner resolved deps fresh, allowing semver-compatible drift to silently introduce broken transitives (the brotli/alloc-no-stdlib mismatch above). The root workspace lockfile plus the per-package nested lockfiles (R, Ruby, Elixir NIF, e2e/rust, test_apps/rust) are now tracked.
* **Pass `--locked` to `cargo build` in CI, publish, scripts, and `alef.toml` hooks.** Now that the lockfile is tracked, every CI/publish cargo build runs with `--locked` so a dirty index can’t silently substitute newer transitive deps. Local-dev tasks (`.task/languages/rust.yml`) intentionally remain without `--locked` so contributors can pick up dep updates.
* **Regenerated cross-language bindings with alef 0.25.1.** Pulls in: csharp e2e codegen using `KreuzbergConverter` facade; swift e2e codegen no longer emits `?` chains on non-Optional `RustString` returns; C e2e codegen panics on missing `fields_c_types` keys instead of silently miscompiling; FFI/NAPI/PyO3/Magnus/Rustler test surface cleanup; `vendor::scrub_or_regenerate_lock` preserves workspace lockfile pins via per-member `cargo update` + `cargo metadata --locked` validation; NAPI strips the `readonly` keyword from emitted `service.cjs`.
## \[3.6.3] - 2026-06-14
[Section titled “\[3.6.3\] - 2026-06-14”](#363---2026-06-14)
### Changed
[Section titled “Changed”](#changed-9)
* **alef extension API: `[crates.ffi].visitor_callbacks` is now backed by the new alef per-extension config mechanism.** alef’s `parse_config` hook now receives the real `[extensions.<name>]` section from `alef.toml` rather than always `None`. The `visitor_callbacks = true` knob in `[crates.ffi]` remains the correct way to enable the visitor/callback FFI pattern — it is a general alef feature shared with Go, Java, C#, and other FFI consumers, not h2m-specific. A new `transform_emitted_files` hook on the `Extension` trait is also available for downstream post- processing of generated files; h2m does not currently use it but can opt in without alef changes.
### Fixed
[Section titled “Fixed”](#fixed-17)
* **CI: `upload-go-release` now gates on `release_go == 'true'`.** The job’s conditional was missing the explicit `needs.prepare.outputs.release_go == 'true'` check, allowing it to run during partial publishes when Go is intentionally skipped. Without this guard, skipped Go builds would still trigger FFI uploads/finalize-release’s go-module-path tagging. Now properly skips when Go release is disabled.
## \[3.6.2] - 2026-06-13
[Section titled “\[3.6.2\] - 2026-06-13”](#362---2026-06-13)
### Fixed
[Section titled “Fixed”](#fixed-18)
* **Python `.pyi`: `ConversionOptions.visitor` attribute type now resolves to `HtmlVisitor | None`.** The class-attribute annotation pass in alef’s pyo3 stub emitter previously printed the opaque `VisitorHandle` concrete type for `Option<dyn HtmlVisitor>` fields, while `__init__` parameters and `convert(...)` already resolved to the `HtmlVisitor` Protocol. Field-style assignment (`options.visitor = MyVisitor()`) is now type-clean under pyright/pylance. Closes #403.
* **NAPI `convert`: visitor callbacks now fire when passed via `options.visitor`.** The generated `convert(html, options)` shim previously declared a third standalone `visitor` parameter and used it directly while ignoring `options.visitor`. The TypeScript surface advertises a single uniform entry point — `convert(html, { visitor: { … } })` — so visitor callbacks routed through `options` were silently dropped. Fixed in alef v0.24.16; the standalone parameter is gone and `options.visitor` is the sole source. Closes #395.
* **NAPI options-field bridge: drop unused `mut` on the closure binding.** The generated `convert(html, options)` shim’s `Option<JsConversionOptions>.map(|o| …)` closure moved `o` straight into `o.into()` without mutating the binding, so `mut o` triggered `warn(unused_mut)` on `crates/html-to-markdown-node/src/lib.rs`. Fixed in alef v0.24.17 by dropping `mut` from the napi-side closure binding; the wasm-side template is unchanged because it does mutate `o.visitor` before the `into()` call.
* **Ruby: precompiled-gem ABI fallback to source-gem.** The `cross_compile_versions` list in the Magnus Rakefile template now targets Ruby 3.5/3.4/3.3/3.2 (dropping 3.1, adding 3.5), and the gemspec `required_ruby_version` bounds the upper edge with `>= 3.2.0, < 4.0`. On Ruby 4.0+ / 4.1.0dev, RubyGems now refuses the precompiled platform gem and falls back to the source gem, eliminating `incompatible ABI version of binary` load failures on prerelease ABIs. Closes #405, #409.
* **C# / Kotlin Android: wrapper class renamed `HtmlToMarkdownRs` → `HtmlToMarkdownConverter`.** The previous `…Rs` suffix was Rust-implementation-bleed in the public binding surface. The new name is idiomatic for both ecosystems and matches the names already used in our hand-written docs. **BREAKING for downstream C# / Kotlin-Android consumers**: apply `s/HtmlToMarkdownRs/HtmlToMarkdownConverter/g` to source code that imported or invoked the wrapper. Closes #408.
* **PHP PIE: macOS install resolves the extension at the archive root.** `pie install xberg-io/html-to-markdown` on macOS arm64 previously failed because the staged extension was named `html_to_markdown.so` while PIE’s `UnixBuild` probes for `<extname>.<dylib_ext>` on macOS. The publish workflow now stages the extension as `html_to_markdown.dylib` on macOS targets and `.so` on Linux, restoring PIE installs on Apple Silicon and Intel Macs. Closes #334.
* **Python wheel: `HtmlVisitor` trait-bridge runtime-import resolved.** alef’s pyo3 trait-marker-class emitter creates `_Trait{Name}Marker` types in the DTO module (`visitor.rs`) to satisfy TypeScript/Ruby/etc. downstream trait surface generation. The PyO3 bridge uses these markers as import-path sentinels, but h2m’s `ConversionOptions` visitor field only became public in v3.6.1 after its prior conditional `#[cfg(feature = "visitor")]` gate was removed. Wheels shipped without the marker import working, causing `ImportError: cannot import name '_TraitHtmlVisitorMarker'` at runtime when user code called `convert(..., visitor)`. Fixed in alef v0.21.0 (marker-import path resolved from the actual DTO module).
* **Java JAR: `NativeLib` RID alignment with publish-workflow classifier names.** The publish workflow (`publish.yaml`) uploads native libraries with RID classifiers: `osx-aarch64`, `osx-x86_64`, `linux-x86_64`, `linux-aarch64`, `windows-x64`. The `NativeLib.scala.kt` loader looked for `osx-arm64` and `osx-x86-64` (mismatched case and infix), breaking native library resolution at JAR initialization. Fixed in alef v0.20.5; RID names now match the publish assets exactly.
* **R tarball: GitHub-release install fixed.** The CRAN tarball sources from GitHub release tags when users install from `.tar.gz` source (non-CRAN edge case). The `configure` script ran `cargo` with `CARGO_HOME=...` override to redirect vendor offline access, but `cargo vendor` itself does not honor `CARGO_HOME` (only cargo build does), so the offline build failed with “could not find `html-to-markdown` in the registry”. extendr 0.18.1 correctly passes `--registry crates-io --offline` through to `cargo vendor`, restoring offline builds. The configure script also fixed inbound `str_as_str` imports from extendr that the v0.18.0 landing initially broke.
* **Homebrew: `brew trust` prerequisite documented.** Homebrew 6.0+ (released 2026-05) requires `brew trust xberg-io/tap` before installing from the third-party tap. Updated `docs/installation.md`, `README.md`, and `test_apps/homebrew/run_tests.sh` with the trust step and explanatory note. Smoke test now calls `brew trust "$TAP" || true` before `brew bundle install`, making CI-tested on Homebrew 6.0+ environments.
### Added
[Section titled “Added”](#added-1)
* **CITATION.cff `date-released:` auto-stamped.** `alef sync-versions --release-date YYYY-MM-DD` now stamps the release date directly into the workspace-generated `CITATION.cff`, eliminating the prior hand-edit step at release-cut time. The release date for v3.6.2 is `2026-06-13`. Closes #327.
## \[3.6.1] - 2026-06-12
[Section titled “\[3.6.1\] - 2026-06-12”](#361---2026-06-12)
### Fixed
[Section titled “Fixed”](#fixed-19)
* **Ruby gem: `Rakefile` reverted to v3.5.5 working pattern.** v3.6.0’s alef 0.21.0 regen introduced `RbSys::ExtensionTask` with manual `Dir.chdir` nesting that broke nested `file "Cargo.lock"` task declarations. Reverts to the v3.5.5 `Rake::ExtensionTask` pattern for all 5 platforms (macOS arm64/x86_64, Linux x86_64/aarch64, Windows x64). Resolves bundle exec compilation failures.
* **Zig: curl HTTP/2 support.** Zig’s vendored curl bindings required `+h2` feature flag for HTTPS URL fetch operations. Updated `packages/zig/build.zig.zon` to enable the feature, restoring GitHub-release downloads on Zig consumers.
* **Homebrew bottle ordering stabilized.** alef v0.20.5 sort order for bottle entries now matches `brew audit` expectations; formulae no longer fail the Homebrew official-tap checklist.
## \[3.6.0] - 2026-06-12
[Section titled “\[3.6.0\] - 2026-06-12”](#360---2026-06-12)
### Added
[Section titled “Added”](#added-2)
* **Tiered HTML to Markdown conversion architecture.** Clean HTML inputs now have an opt-in fast path through a Tier-1 single-pass byte scanner (`converter/tier1/`); on anything the scanner cannot prove byte-equivalent to the existing Tier-2 DOM walker, it returns a structured bail and the dispatcher falls back to Tier-2 (`tl::parse` + `walk_node`) transparently. Output is always byte-equal to what Tier-2 would have produced for the same input — verified by 116 oracle snapshots and a per-fixture byte-equality integration test (`tests/tier1_byte_equality_test.rs`). Tier-3 (`html5ever` repair) remains the fallback for truly malformed HTML.
* **`ConversionOptions::tier_strategy`** (`TierStrategy::Auto` | `Tier2` | `Tier1`) for runtime tier selection. `Auto` (default) lets the classifier decide based on the prescan signals and options shape; `Tier2` forces the existing DOM-walk path; `Tier1` is testkit-only (`#[cfg(any(test, feature = "testkit"))]`) for debugging and benchmarking. Exposed to Node (`tierStrategy: "auto" | "tier2"`) and Wasm (`WasmTierStrategy` enum). CLI and Python pick up the field via the standard options-mapping flow.
* **Tier-1 router style-option gate.** The classifier forces Tier-2 when any of these deviate from Tier-1’s hardcoded value: `heading_style`, `code_block_style`, `strong_em_symbol`, `bullets`, `list_indent_*`, `whitespace_mode`, `newline_style`, `escape_*` flags, `output_format`, `link_style`, `url_escape_style`, `compact_tables`, `default_title`, `sub_symbol`, `sup_symbol`, `highlight_style`. 47 integration tests enforce the gate.
* **Tier-1 conservative bail set.** Tier-1 returns `Err(BailReason::*)` rather than emit potentially-wrong output on: custom elements, CDATA, unescaped `<`, inline SVG, HTML 5 optional-close edge cases, `<table>` with rowspan/colspan/block-children-in-cells/ caption/mixed-section-order, nested lists (Tier-2 cycles bullets by depth), `<pre>` with non-Indented `code_block_style`, named HTML entities outside the 45-entry zero-alloc table, table cells containing `|`, and `<br>` inside table cells. Tests cover every variant.
* **Benchmark harness** (`tools/benchmark-harness/`, binary `htmbench`) with `run` / `compare` / `oracle` / `oracle:bless` / `survey` / `mdream` subcommands. Per-group regression guardrails (`baselines/baseline.json`, `guardrails.json`). Wired under `task bench:*` namespace.
* **Bench regression gate in CI** — every PR that touches the Rust core or bench harness now runs `task bench:oracle && task bench:run && task bench:compare` on `ubuntu-24.04-arm`, failing on any fixture that exceeds its per-group threshold in `tools/benchmark-harness/guardrails.json` (5% clean_large, 8% clean_medium, 10% other groups, 30% adversarial). Baselines are blessed deliberately by humans, not automatically by CI.
### Changed
[Section titled “Changed”](#changed-10)
* **Publish workflow now authenticates via the `kreuzberg-dev-publisher` GitHub App** (org-level `BOT_APP_ID` / `BOT_APP_PRIVATE_KEY`) for all writes (own-repo pushes, tag updates, release-asset uploads, homebrew-tap commits, Discord dedup marker). OIDC publisher jobs (PyPI/npm/hex/Maven/NuGet/crates) are unaffected. `HOMEBREW_TOKEN` is no longer used.
* **BREAKING: `NodeContext::attributes` is no longer a public field.** Access attributes via the new `attributes()` method (`fn attributes(&self) -> &BTreeMap<String, String>`). Struct-literal construction of `NodeContext` is no longer possible; use the provided constructors: `with_borrowed_attributes`, `with_owned_attributes` (public), or `with_lazy_attributes` (pub(crate), for internal use only). Attributes are now lazily materialized from the DOM on first access when constructed via the internal path, eliminating the per-element `BTreeMap` allocation on the visitor hot path. Measured throughput improvement with visitor enabled (100-iteration harness, Apple Silicon): small_html −29%, medium_python −10%, large_rust −24%, tables_countries −24%.
* **`DomContext::parent_tag_name` now returns `Option<&str>` instead of `Option<String>`.** This is an internal API (`pub(crate)`); external consumers are unaffected.
### Performance
[Section titled “Performance”](#performance)
* **Tier-1 byte scanner activated in production** (`tier_strategy = Auto`). The classifier decides per-input whether Tier-1’s single-pass byte scanner runs; on bail, the dispatcher falls back to Tier-2 transparently. Measured throughput on the harness corpus (29 fixtures, 6.4 MB total; Apple Silicon, `cargo build --release`):
| Fixture | Size | ms (best) | Throughput |
| ------------------------------------------- | ------- | --------- | ---------- |
| `real-world/wikipedia/medium_python.html` | 1.24 MB | 62.58 ms | 19.0 MB/s |
| `real-world/wikipedia/large_rust.html` | 1.07 MB | 37.17 ms | 27.3 MB/s |
| `mdream/github-markdown-complete.html` | 430 KB | 10.57 ms | 38.7 MB/s |
| `mdream/react-learn.html` | 265 KB | 12.11 ms | 20.9 MB/s |
| `mdream/wikipedia-small.html` | 166 KB | 5.63 ms | 28.1 MB/s |
| `real-world/issues/gh-121-hacker-news.html` | 57 KB | 1.08 ms | 50.3 MB/s |
| `mdream/nuxt-example.html` | 3.6 KB | 0.029 ms | 116.1 MB/s |
Per-group regression thresholds (5–30%) are enforced on every PR via `task bench:compare` (see Added section).
* **memchr-driven text scan**: `decode_and_collapse_into` and `decode_entities_into` use `memchr::memchr3` / `memchr::memchr` to skip ahead to the next special byte (`<`, `&`, whitespace boundary) and bulk-copy plain text runs in a single `push_str`. Replaces a byte-by-byte conditional inner loop and closes a substantial portion of the gap to main’s heavily-optimized Tier-2 path on Wikipedia-scale documents (e.g., +32% on `wikipedia-small`).
* **Tier-1 dispatcher reuses normalized input on Tier-2 fallback.** When the Tier-1 scanner bails or the classifier routes to Tier-2, the dispatcher threads the already-computed `normalize_input` `Cow<str>` through to the Tier-2 path instead of recomputing it. Eliminates one full-input pass on every bail-fallback or Tier-2-routed call.
* **`collapse_excess_blank_lines` in-place.** Replaced the fresh-`String` rewrite with `String::retain`, eliminating an output-sized allocation on every Tier-1 success whose output contains `\n\n\n`. Measured wins (best-of-3, `--force-tier1`, vs prior commit): `wikipedia/lists_timeline` -3.81%, `gh-121-hacker-news` -4.23%, `github-markdown-complete` -2.99%, `wikipedia/medium_python` -2.94%, `mdream/wikipedia-small` -2.68%, `mdn-array` -2.12%, `gh-190/firsteigen` -2.55%. No fixture regressed.
* **`htmbench --force-tier2`** flag mirroring `--force-tier1`, for clean head-to-head benchmarks now that the Auto router activates Tier-1 on most fixtures and so cannot be used as a Tier-2 control.
* **`convert()` accepts options as a bare `ConversionOptions`** in addition to `Option<ConversionOptions>` (resolves #398). The second parameter now bounds `impl Into<Option<ConversionOptions>>`, so `convert(html, opts)`, `convert(html, Some(opts))`, `convert(html, None)`, and `convert(html, ConversionOptions::default())` are all valid Rust call shapes. Existing callers continue to compile unchanged — this is purely additive flexibility, not a breaking change. The \~250-line conversion body is held in a private non-generic `convert_inner` so the generic wrapper monomorphises exactly once per call site rather than per `Into` impl chosen.
* **`url_escape_style` option** (`UrlEscapeStyle::Angle` | `UrlEscapeStyle::Percent`). When set to `Percent`, link and image destinations are percent-encoded instead of wrapped in angle brackets, producing output that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses (resolves #392).
### Fixed
[Section titled “Fixed”](#fixed-20)
* **Non-deterministic SVG attribute serialization** in `converter/media/svg.rs`: `serialize_element` iterated `tag.attributes()` over astral-tl’s internal `HashMap`, which has non-deterministic iteration order. SVG `data:` URIs therefore differed across runs. Fixed by sorting attributes by name before emission, restoring determinism.
* **spurious blank lines after frontmatter and lists (MD012)** (resolves #399). Block-level emission now collapses runs of three or more consecutive newlines into exactly two, so the frontmatter→body and list→next-block transitions no longer produce extra blank lines that violate markdownlint MD012.
* **autolinks: bare paths and filenames are no longer wrapped as autolinks** (resolves #397). Per GFM §6.5, autolinks require an absolute URI with a scheme — but the previous check only compared the link text to the `href`, so `<a href="foobar.png">foobar.png</a>` became the invalid `<foobar.png>` (which parsers read as a literal HTML tag). Added `has_uri_scheme` helper that validates the RFC 3986 scheme grammar (`ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )` followed by `:`). Bare paths, fragments, and filenames now render as `[text](href)`. `https://`, `mailto:`, `ftp://`, `data:`, and other schemed URLs continue to autolink as before.
* **node binding: visitor callbacks (`visitText`, `visitLink`, `visitHeading`, …) now fire** (resolves #395). `JsHtmlVisitorBridge` now stores a persistent `napi::bindgen_prelude::ObjectRef<false>` obtained via `Object::create_ref()` and materializes a fresh local `Object` handle per callback through `obj_ref.get_value(&env)`. The previous bridge stored raw `napi_value` pointers extracted via `transmute_copy` and reconstructed via `Object::from_raw` — but a `napi_value` is a local handle tied to the HandleScope active at construction time, and by the time visitor methods fired deep inside `convert()` the scope was no longer active, so `get_named_property("visitText")` silently returned `Err` and the bridge fell through to `VisitResult::Continue` without dispatching. A `Drop` impl on the bridge calls `obj_ref.unref(&env)` so the JS object can be GC’d after conversion. Verified against the issue repro: `visitText`/`visitLink`/`visitHeading` all fire. (alef commit `1ffdaafe4`)
* **code block: `CodeBlockStyle::Backticks` and `Tildes` no longer emit a trailing blank line inside the fence and now insert a blank line after the closing fence** (resolves #396). The fenced emitter pushed `content` verbatim (which already ends in `\n` for any trailing-newline source) plus an extra `\n` before the closing fence, producing `…\n\n```\n`. It also closed with a single `\n`, so following block content butted up against the closing fence with no blank line separator — `Indented` style was unaffected because its content path strips trailing newlines via `.lines().join("\n")` and already emits `\n\n` after. The Backticks/Tildes path now trims trailing newlines from inner content (`content.trim_end_matches('\n')`) before re-emitting a single `\n`, and pushes `\n\n` after the closing fence to match Indented.
* **php test_app: PIE `install.sh` now installs `xberg-io/html-to-markdown`** instead of the non-existent `xberg-io/html-to-markdown-rs` (resolves #98 / smoke regression). The Packagist project only publishes the un-suffixed name; `alef.toml` was renamed and the regen picks it up in both `install.sh` and the inline comment.
* **r binding: `conversion_options()` helper exported in `NAMESPACE`.** alef’s R emitter generated the `R/options.R` helper for ergonomic ConversionOptions construction but never exported it, so `htmltomarkdown::conversion_options(...)` raised `could not find function` at runtime — which downstream `convert(..., options=)` callers then surfaced as the extendr-api 0.9.0 `options must be a named list` validation error. Resolves #99 / smoke regression. (alef commit `160d504f3`)
* **java binding: `NativeLib.<clinit>` no longer throws `NoSuchElementException`** when an optional FFI symbol is missing. The error-context handle lookups (`LAST_ERROR_CODE`, `LAST_ERROR_CONTEXT`) used `Optional.orElseThrow()` mid-static-init, escalating any partial symbol set into a hard `NoClassDefFoundError`; they now fall back to `null` and the rest of the loader’s null-checks handle the absence gracefully. Resolves #100 / smoke regression. (alef commit `d296bfdeb`)
* **c FFI test_app `Makefile` now embeds an `LC_RPATH`** so the smoke binary can find the dylib at runtime on macOS without `DYLD_LIBRARY_PATH`. Adds `-Wl,-rpath,$(FFI_LIB_DIR)` to the LDFLAGS path. Resolves #101 / smoke regression.
* **csharp binding: trait-bridge catch blocks no longer emit unused `Exception ex` variables.** The generated `TraitBridges.cs` had 25+ `catch (Exception ex)` blocks where `ex` was never referenced; with `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` the build failed with CS0168, which in turn blocked NuGet publish for 3 releases (root cause of #104). alef now emits bare `catch (Exception)` when the exception variable isn’t actually used. (alef commit `16e81b20d`)
### CI/Publish
[Section titled “CI/Publish”](#cipublish)
* **`.npmrc` at workspace root: `minimum-release-age=0`** so the npm `Build Node bindings` and `Build WASM package` jobs stop failing at `pnpm install` time with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` for transitively-recent dep pins. The v3.5.5 fix only patched the test command; this covers every `pnpm install` call repo-wide. Resolves #96.
* **Go subtag publish** (`packages/go/v3.5.x`) is already wired through the `xberg-io/actions` `finalize-release` job (publish.yaml:2418 passes `go-module-path: packages/go/v3`); no action needed here. The reason v3.5.2–v3.5.7 didn’t push subtags is upstream main-release-job failures cascading. Resolves #97.
### Chore
[Section titled “Chore”](#chore)
* **alef pin: 0.20.12 → 0.21.0** (local unreleased head; no alef tag). Bindings + e2e suites regenerated against the freshly-rebuilt local alef binary, picking up the cohort fixes above in a single regen.
## \[3.5.7] - 2026-05-29
[Section titled “\[3.5.7\] - 2026-05-29”](#357---2026-05-29)
### Fixed
[Section titled “Fixed”](#fixed-21)
* **release: sync workspace `Cargo.toml` version.** v3.5.6’s release commit (`2c37942f8`) claimed to bump the workspace version 3.5.5 → 3.5.6 but the change never actually landed in the commit. Every binding manifest (Cargo.toml, pyproject.toml, gemspec, mix.exs, pom.xml, .csproj, package.json, …) stayed pinned at 3.5.5, so the v3.5.6 publish workflow built v3.5.5 binaries against the v3.5.6 tag and uploaded them as `*-v3.5.5-*.tar.gz` assets to the v3.5.6 GitHub Release. crates.io / PyPI / Hex / RubyGems / Maven publishes were either no-ops (3.5.5 already exists) or rejected; npm + WASM + NuGet + Homebrew steps also failed. v3.5.6 is skipped; v3.5.7 is the corrected ship of every fix originally rolled into v3.5.6.
* **alef pin: 0.20.11 → 0.20.12** (auto-synced by `alef sync-versions`).
### Chore
[Section titled “Chore”](#chore-1)
* **bindings: regenerated against alef v0.20.12** with workspace version correctly bumped to 3.5.7 first, so every manifest now matches the release tag.
## \[3.5.5] - 2026-05-28
[Section titled “\[3.5.5\] - 2026-05-28”](#355---2026-05-28)
### Fixed
[Section titled “Fixed”](#fixed-22)
* **ci(ruby): cross-compile `windows-x64` gem via `bundle install` inside the `rb-sys-dock` container.** The previous matrix entry ran `rb-sys-dock --platform ... -- bundle exec rake "native[$target]" gem`, which invoked `bundle exec` inside the container without first materialising the lockfile against the container’s Ruby version. The rb-sys-dock container ships its own Ruby toolchain (4.0.2 preview) while the host `Gemfile.lock` pins 3.3.11, so bundler failed with “Could not find …” and hung for 47 minutes. The command now wraps the container invocation in `bash -c "bundle install --jobs=4 --retry=3 && bundle exec rake …"` so the lockfile materialises against the container’s Ruby before `rake` runs. (`.github/workflows/publish.yaml`)
* **ci(elixir): Hex publish no longer 404s on darwin tarball downloads.** alef v0.20.2 changed darwin NIF tarballs to `.dylib.tar.gz` to “match the platform-native extension,” but `rustler_precompiled 0.9.0` (the latest version on Hex; no `.dylib`-aware version exists) hardcodes `.so` for every non-Windows consumer download URL in `lib_name_with_ext/2` and ignores all caller overrides. h2m’s hand-maintained publish.yaml had already normalised darwin uploads to `.so`, so h2m’s own Hex publish kept working; the bug only surfaced in sibling polyglot repos. The alef v0.20.5 revert (`.dylib` → `.so`) restores polyrepo alignment and is picked up by this regen. (`alef.toml` pin → `v0.20.5`, `xberg-io/actions/generate-elixir-checksums@v1`)
* **bindings(c): registry test_app `download_ffi.sh` now hits the correct release asset prefix.** The `[crates.e2e.registry.packages.c] name` was `html-to-markdown-ffi`, but `publish.yaml` uploads C FFI tarballs with `asset-prefix: html-to-markdown-rs-ffi-`. Drift caused `task test-apps:smoke:c` to 404 on the GH release tarball. (`alef.toml`)
* **bindings(java): registry test_app now ships the Maven wrapper (`mvnw`, `mvnw.cmd`, `.mvn/wrapper/maven-wrapper.properties`).** Previously missing because mvnw emission landed in alef v0.20.2 and h2m was pinned at v0.20.1. (`alef.toml` pin → `v0.20.5`)
* **bindings(homebrew, c, …): every alef-emitted `*.sh` (e.g. `run_tests.sh`, `download_ffi.sh`) is now created with the `+x` bit set.** alef’s `write_scaffold_files_with_overwrite()` skipped the shebang-chmod helper that `write_files()` applied, so every alef-generated shell script in `e2e/` and `test_apps/` landed as `-rw-r--r--`, breaking `task test-apps:smoke:homebrew` with “permission denied” on `./run_tests.sh`. Fixed by alef v0.20.3’s shared `apply_shebang_chmod()` helper called from both writers. (`alef.toml` pin → `v0.20.5`)
* **bindings(go, php, swift, csharp, dart, kotlin_android, zig, …): trait-bridge codegen cohort fixes.** PHP refcount safety (inc_count/dec_count via PhpRc), Go duplicate //export removal + cgo.Handle.Delete defer/recover, Swift async/throws + try await order + JSON-encode conditionally, C# callback method naming + bool→int + IntPtr userData + usize/isize mapping, Dart trait-import + factory wrapper required-only methods + RID-aware published-loader, Kotlin Android useJUnitPlatform() in registry mode, Zig error-union removal from test-backend stubs, Java trait-method emission incl. default-impl methods + `ffi_skip_methods` honouring in `I{Trait}` interface emission. (`alef.toml` pin → `v0.20.5`)
* **bindings(elixir): rustler upgraded 0.37 → 0.38.** (`packages/elixir/native/html_to_markdown_nif/Cargo.toml`)
* **bindings(php): PHP trait-bridge async no longer panics on “Cannot start a runtime from within a runtime.”** Generated async method bodies now prefer `Handle::try_current()` before `WORKER_RUNTIME.block_on(...)` so the bridge is safe to call from within an outer tokio runtime. (`alef.toml` pin → `v0.20.5`)
* **bindings(wasm, node): test_apps pass `--config.minimumReleaseAge=0` to `pnpm test` so freshly-published RC packages clear pnpm’s supply-chain policy check.** (`alef.toml` pin → `v0.20.5`)
### Chore
[Section titled “Chore”](#chore-2)
* **bindings: regenerated against alef v0.20.5.** Folds in every fix from v0.20.2 through v0.20.5 — see alef CHANGELOG for the full backend cohort.
* **deps(java): jackson-databind + jackson-datatype-jdk8 2.21.2 → 2.21.3.** (`packages/java/pom.xml`)
* **deps(rust): reqwest 0.13.3 → 0.13.4 in CLI binary.** (`crates/html-to-markdown-cli/Cargo.toml`)
* **deps(js): pnpm packageManager 11.3.0 → 11.4.0.** (`package.json`)
* **taskfile(elixir): tolerate `mix hex.outdated` non-zero exits before `mix deps.update --all`.** (`.task/languages/elixir.yml`)
## \[3.5.4] - 2026-05-28
[Section titled “\[3.5.4\] - 2026-05-28”](#354---2026-05-28)
### Fixed
[Section titled “Fixed”](#fixed-23)
* **ci(node): restore alef-generated `index.d.ts` after `napi build` in the `node-typescript-defs` publish job.** The napi-rs macros deliberately filter out the `*Update` DTO types (`ConversionOptionsUpdate`, `PreprocessingOptionsUpdate`), so the d.ts regenerated by `napi build` lacks them; the wrapper at `packages/typescript/src/index.ts` re-exports those names and `tsc` fails with TS2724 on every publish. The publish job now `git checkout HEAD -- crates/html-to-markdown-node/index.d.ts` between `napi build` and the artifact copy, preserving alef’s augmented d.ts.
* **ci(ruby): cross-compile `windows-x64` gem via `rake-compiler-dock` from the Linux runner.** The previous matrix entry’s `cargo build --target x86_64-pc-windows-gnu` against the ucrt64 MSYS2 toolchain corrupted a linker argument and failed every release with `cannot find -l■`. Linux-host docker-based `rake-compiler-dock` is rb-sys’s recommended cross-build path and matches what every other rb-sys gem uses for Windows.
* **bindings(elixir): `RustlerPrecompiled` now resolves the correct platform extension on macOS.** v0.20.0’s rustler emit lets RustlerPrecompiled’s built-in mapping pick `.dylib` for `*-apple-darwin` targets and `.so` for `*-linux-*`, so `mix deps.get` no longer 404s against `*.so.tar.gz` on darwin consumers.
* **alef hash: per-file `alef:hash:` now computed over generation inputs, not emitted content.** Post-format whitespace drift no longer invalidates `alef verify`, so CI Lint stops reporting bindings as stale after every prek `--all-files` cycle.
* **bindings(java): test_app pom.xml drops `-Djava.library.path=.../target/release` in registry `dep_mode`.** The Maven-Central JAR bundles natives under `/natives/{rid}/` and alef’s loader extracts them at startup; overriding the library path to a non-existent local directory broke `UnsatisfiedLinkError` on smoke runs. Override is now emitted only in local `dep_mode`.
* **bindings(c): test_app Makefile no longer requires a local `target/release/` build to resolve the FFI.** `download_ffi.sh` is skipped only when both the FFI header and shared library are present locally; otherwise the published tarball is fetched. Smoke runs from a clean checkout work without a prior `cargo build`.
* **bindings(php): registry test_app installs the PIE-distributed extension via `install.sh` before `composer install`.** Removes the implicit “ext-html_to_markdown must be pre-installed” requirement.
### Chore
[Section titled “Chore”](#chore-3)
* **bindings: regenerated against alef v0.20.1.** Folds in B6 hash semantics, java/c e2e build-path fixes, php install.sh, vendored Cargo workspace marker, scaffold persistence (rustc job cap + Node memory cap), wasm e2e import dedupe, service_api emitter family for csharp/dart/go/swift/zig/jni/ffi/extendr/napi/magnus/php/rustler/pyo3 with real dispatch (not yet wired in h2m but available for downstream features), zig platform-suffixed URLs in build.zig.zon, kotlin nullable bare result assertions, and php anonymous-class super_trait `name()` dedup.
## \[3.5.3] - 2026-05-27
[Section titled “\[3.5.3\] - 2026-05-27”](#353---2026-05-27)
### Fixed
[Section titled “Fixed”](#fixed-24)
* **core: prevent silent truncation on XHTML-style self-closing tags (`<td/>`, `<br/>`, etc.) embedded in EPUB-derived HTML.** The bundled astral-tl parser treats `/` as an identifier character, so `<td/>` was parsed as a tag literally named `"td/"` and subsequent siblings nested under it — table rows collapsed into a single cell and any content after the broken table was dropped. `convert_api::normalize_input` now preprocesses `<tag/>` → `<tag />` before tokenization so the trailing slash is read as a self-closing marker. Regression covered by `tests/issue_391_xhtml_self_closing.rs`. Closes #391.
* **docs(python): visitor API reference rewritten to match the actual duck-typed binding.** The generated `docs/reference/api-python.md` documented a `class MyVisitor(VisitorHandle):` subclass pattern with `VisitResult.Continue` enum returns, but `VisitorHandle` is `#[pyclass(unsendable, from_py_object)]` (sealed; cannot be subclassed) and `VisitResult` exposes only property getters (`VisitResult.Continue` raises `AttributeError`). The trait rustdoc on `HtmlVisitor` now leads with the plain-class + string/dict return idiom that the magnus-style bridge actually accepts. Closes #389.
* **packaging(python): unblock PyPI sdist build from Alpine/musl and other no-precompiled-wheel platforms.** PyPI 3.5.1’s sdist was missing the core `crates/html-to-markdown/` directory because a stale `.gitmodules` entry pointing at a deleted `homebrew-tap` submodule caused `cargo package --list` to fail silently during the CI maturin run, so maturin only bundled the PyO3 crate and shipped a sdist that could not build. Removed the stale `.gitmodules`; maturin’s path-dependency auto-bundling now works again and the resulting sdist contains all 177 core-crate files. Closes #390.
* **ci(swift): Swift Artifact Bundle publish job uses the renamed crate `html-to-markdown-rs-swift`.** Stale `html-to-markdown-swift` reference broke the Swift bundle step on every release since v3.5.0.
### Chore
[Section titled “Chore”](#chore-4)
* **bindings: regenerated against alef v0.19.22.** Pulls in the e2e green-up cohort (csharp/php/extendr/rustler/swift/zig/dart/go/java/ruby/elixir trait-bridge emitter fixes) and drops alef’s broken `[tool.maturin] include` directive (maturin rejects archive paths with `..`).
## \[3.5.2] - 2026-05-26
[Section titled “\[3.5.2\] - 2026-05-26”](#352---2026-05-26)
### Fixed
[Section titled “Fixed”](#fixed-25)
* **bindings(csharp): trait-bridge facade methods now throw the per-binding `HtmlToMarkdownRsException` instead of an undefined `KreuzbergException`.** The alef csharp backend’s register/unregister facade method emitter was hardcoded to `KreuzbergException` (the kreuzberg core lib’s exception class), causing every C# build to fail with `CS0246: KreuzbergException could not be found`. Fixed in alef 0.19.13 and pulled in by this regen.
* **bindings(swift): `RustBridgeC.h` placeholder now declares the `RustStr` C struct that `SwiftBridgeCore.swift` depends on.** Without the typedef the Swift compiler reported `cannot find type 'RustStr' in scope` for every `extension RustStr` block before the full `cargo build` populated the real header. Fixed in alef 0.19.13.
* **bindings(swift): resolve Swift Package Manager “unsafe build flags” rejection for v3.5.2+.** Swift 6.0+ strictly rejects packages with `unsafeFlags` in public products to prevent supply-chain code injection. The root `Package.swift` used by external consumers (via `.package(url: "...", from: "...")`) is now removed from git; it will be regenerated at release time with `.binaryTarget` pointing to pre-built xcframework/artifactbundle assets. For v3.5.2+, consumers will receive binary distribution (no Rust compilation required). For source builds, developers use `cd packages/swift && swift build` after `cargo build -p html-to-markdown-rs-swift`. The in-tree `packages/swift/Package.swift` retains `unsafeFlags` for local development. This fixes the blocking error for v3.5.1 external consumers attempting to depend on the package.
## \[3.5.1] - 2026-05-25
[Section titled “\[3.5.1\] - 2026-05-25”](#351---2026-05-25)
### Fixed
[Section titled “Fixed”](#fixed-26)
* **bindings(ruby): expose `ConversionOptions.visitor` and wire the magnus visitor bridge end-to-end.** The Ruby gem previously dropped `VisitorHandle` from codegen via `[crates.ruby] exclude_types`, so the documented `HtmlToMarkdown.convert(html, MyVisitor.new)` example silently ignored the visitor and emitted default markdown. Removed the exclusion — alef’s magnus backend already implements the full visitor trait bridge, so the regen produces a working `RbHtmlVisitorBridge` that dispatches each `visit_*` callback via `respond_to?` + `funcall` and translates Ruby return values (`:continue` / `:skip` / `:preserve_html` / `{custom: "..."}`) into `VisitResult` variants. Closes #388.
* **bindings(elixir): expose `ConversionOptions.visitor` and wire the rustler visitor bridge end-to-end.** Same fix as Ruby: removed `VisitorHandle` from `[crates.elixir] exclude_types`. The alef rustler backend already ships the bridge — a system thread runs the conversion, sends `{:visitor_callback, ref_id, callback_name, args_json}` to the caller, and blocks on `HtmlToMarkdown.Native.visitor_reply/2` until the receive loop in `HtmlToMarkdown.convert/2` dispatches the user’s visitor map and replies. Visitor maps are keyed by callback name (`"visit_link"`, `"visit_text"`, …) with one-arity function values.
* **list**: nested-list duplication in Markdown output and the document structure collector (PR #385, fixes [kreuzberg#1004](https://github.com/xberg-io/kreuzberg/issues/1004)). `push_list_item` was previously called with `output[item_start_pos..]`, which included the rendered Markdown of nested `<ul>`/`<ol>` children. Inner items’ text was triple-counted: once as the item itself, once inside the parent item’s text, and once as free text from the walker. A `text_end_pos` cursor now advances only past non-list children. Affects any `ul > li > ul` (or arbitrarily nested) shape.
* **alef.toml**: dropped stale Ruby/Elixir `vendor_mode = "core-only"` overrides — alef now defaults source-build languages to `vendor_mode = "registry"` (the migrated install-from-crates.io flow), and the shared `build-ruby-gem` / `build-elixir-hex` actions enforce the same rewrite at workflow time. Overriding to `core-only` would silently vendor the core crate into `packages/{ruby,elixir}/vendor/` and leave the manifest pointing at the workspace path, which fails to resolve on consumer machines.
* **crates/html-to-markdown-py/src/pyproject.toml**: maturin `manifest-path` corrected to `../Cargo.toml` (was `../../crates/html-to-markdown-py/Cargo.toml`, which resolved to `crates/crates/…` from the pyproject’s own directory). Local `uv sync --upgrade` / `task upgrade` now completes; the publish workflow builds via `maturin build` with explicit paths and was not affected.
* **packages/swift/rust/src/lib.rs**: regenerated against alef 0.19.7 with the swift-bridge inbound trait phantom fix. The previous alef emitted `Vec<Swift{Trait}BoxBox>` in the `extern "Rust"` block (double-`Box` suffix), which swift-bridge-build rejected with “Type must be declared with `type >`”. The inbound phantom is now omitted entirely — `Swift{Trait}Box` is an `extern "Swift" type` with no Rust-side struct backing it, and the Vec accessors are not consumed by the bindings we emit.
* **.task/languages/kotlin_android.yml** + **alef.toml `[crates.update.kotlin_android]`**: the `com.github.ben-manes.versions` Gradle plugin (current pin 0.52.0, latest 0.53.0) throws `java.util.ConcurrentModificationException` under Gradle 9.5.1 on every `:dependencyUpdates` invocation; the plugin has not shipped a release since 2024-11. Both `alef update --latest` and `task kotlin_android:upgrade` previously failed the rest of the upgrade chain. Inert-echo the probe in both places until upstream lands a Gradle 9 fix or we swap to `nl.littlerobots.version-catalog-update`.
### Added
[Section titled “Added”](#added-3)
* **`alef test-apps generate` first-class subcommand**, bundled into `alef all` as a discrete pipeline stage so registry-mode test_apps regenerate alongside the local-mode e2e suite. Per-stage stale-file sweep prevents either output dir (`e2e/` vs `test_apps/`) from deleting the other’s files (the bug that wiped half of `test_apps/` when `alef all` ran in the previous topology).
* **Two new test_app channels** emitted by the new subcommand: `test_apps/homebrew/` (Brewfile + `run_tests.sh` + `ffi_smoke.c` — exercises both Homebrew formulae via `brew bundle install` and a pkg-config-linked C smoke test) and `test_apps/php_ext/` (PIE-installed native ext driver — `pie install xberg-io/html-to-markdown-ext` then `extension_loaded` + convert smoke).
* **alef-generated `build.gradle.kts` for `test_apps/kotlin_android/`** — registry mode consumes the published `dev.kreuzberg:html-to-markdown-android:3.5.x` Maven artifact instead of the local workspace AAR.
* **Taskfile**: `e2e:smoke:homebrew` and `e2e:smoke:php_ext` entries wired into the `e2e:smoke:all` aggregator.
* **`.gitattributes`**: marks `test_apps/**` as `linguist-generated=true` (via the alef-scaffold change that now reads `[e2e.registry].output`).
### Docs
[Section titled “Docs”](#docs)
* **`docs/snippets/ruby/visitor/basic_visitor.md`** rewritten against the magnus-real API: visitor is a positional second argument to `HtmlToMarkdown.convert`, callbacks dispatch via `respond_to?` + `funcall`, return values are `:continue` / `:skip` / `:preserve_html` / `{ custom: "..." }`, the `ctx` argument is a Hash with `:node_type` / `:tag_name` / `:depth` / etc. The previous snippet used a `visitor: MyVisitor.new` kwarg form and `result[:content]` accessor that don’t match the gem’s actual surface.
* **`docs/snippets/elixir/visitor/basic_visitor.md`** rewritten against the rustler-real API: visitor is a `%{"visit_*" => fn args -> ... end}` map under the `:visitor` key of the options Hash; the bridge sends `{:visitor_callback, ref_id, callback_name, args_json}` messages and blocks on `visitor_reply/2`. The previous snippet used an aspirational `use HtmlToMarkdown.Visitor` behaviour form that alef does not generate.
### CI
[Section titled “CI”](#ci)
* **`publish-swift` job removed** from `.github/workflows/publish.yaml`. Swift Package Index has no central registry — packages are consumed directly from git tags, so the tag push IS the publish event. The previous `check-spi-swift` + `publish-swift` jobs only pinged SPI for fast re-indexing (SPI auto-discovers tags within \~1h without a ping). Cuts runner cost; SPI catches up automatically.
* **`publish-zig` retained** — appends the tarball URL + SHA-256 to the GitHub Release notes via `update-release-notes: true`, which downstream consumers copy directly into `build.zig.zon`.
* **`actions/publish-hex` bumped to v1.6.9**: generates `Cargo.lock` for every `native/**/Cargo.toml` before `mix hex.publish`. The lockfile is gitignored, so the publish action’s fresh checkout had nothing to publish; this mirrors the `build-elixir-hex` fix from earlier in the v3.5.0 cycle.
* **`task upgrade` works end-to-end again** after the Python and Kotlin Android fixes above.
## \[3.5.0] - 2026-05-25
[Section titled “\[3.5.0\] - 2026-05-25”](#350---2026-05-25)
### Fixed
[Section titled “Fixed”](#fixed-27)
* **bindings: regenerated with alef 0.19.6.** Node optional-dep package names now carry the `@kreuzberg/` scope (`@kreuzberg/html-to-markdown-node-<target>`) so `requireOptionalDependency()` resolves the published per-platform packages instead of an unscoped name that does not exist on npm. `test_apps/` restructured by alef to the new layout (per-language runners under `test_apps/<lang>/{ffi,htm_test,run_tests}` for C; legacy in-tree test files removed). Additional alef-emitter, swift-bridge, FFI param handling, and ahash-scaffold fixes carried through from the 0.19.x line.
* **ci(publish-hex): bump to xberg-io/actions\@v1.6.9 — generate `Cargo.lock` before `mix hex.publish`.** `publish-hex@v1` runs a fresh `actions/checkout`, so the gitignored `packages/elixir/native/html_to_markdown_nif/Cargo.lock` is absent and `mix hex.publish` fails with `Missing files: native/html_to_markdown_nif/Cargo.lock`. v1.6.9 mirrors the `build-elixir-hex` fix and runs `cargo generate-lockfile` for every `native/**/Cargo.toml` before publishing. (`v1` floating tag retagged.)
* **ci(publish): rename Go FFI tarballs to use `-go-` infix instead of `-ffi-`.** alef 0.19.6’s Go packager (`alef publish package --lang go`) emitted `{crate}-ffi-v{version}-{platform}.tar.gz`, colliding with the C FFI packager’s prefix. `check-registry` asset-prefix probes and `verify-release-assets` pattern lists could not distinguish Go from C FFI tarballs, so `verify-release-assets` failed on the missing `html-to-markdown-rs-go-*.tar.gz` pattern. Workaround: rename `-ffi-v` → `-go-v` immediately after `alef publish package --lang go` in the workflow. The alef-side fix is already on alef main; the workaround can be dropped once the local alef pin moves to a release that ships it.
* **ci(actions/build-elixir-hex): generate `Cargo.lock` unconditionally after `rewrite-native-deps`.** The fallback `cargo generate-lockfile` only ran on dry-run, but the lockfile is gitignored — real-release runs hit `Missing files: native/html_to_markdown_nif/Cargo.lock` at `mix hex.build`. Now runs in both modes. (xberg-io/actions v1.6.6, floating `v1` retagged.)
* **ci(publish): split Dart pub.dev publishing into a workflow_dispatch flow so OIDC trusted publishing succeeds.** pub.dev’s OIDC verifier rejects tokens minted by `release` events (`Authentication failed!`) and only accepts `push` / `workflow_dispatch`. The publish workflow now assembles the Dart package as an artifact under the `release`-triggered run, then dispatches a separate `publish-pubdev.yaml` workflow (`workflow_dispatch`) that downloads the artifact and runs `dart-lang/publish-pub@v1`. The dispatched job inherits a token GitHub’s OIDC provider mints with `event_name == workflow_dispatch`, which pub.dev’s audit accepts.
* **ci(actions/homebrew-build-bottles): suppress `brew config` SIGPIPE under `pipefail` on arm64 Linux runners.** The arm64 runner’s `/usr/bin/ldd` writes more output than `head -20` consumes; under `set -o pipefail` the broken-pipe propagated out of the early diagnostic block and aborted the script before any bottle work. Temporarily disables `pipefail` for the diagnostic stanza only — strict mode is restored before the build phase. (xberg-io/actions v1.6.7, floating `v1` retagged.)
* **bindings: regenerated with alef 0.19.5.** Picks up the Kotlin Android trait-bridge codegen fixes that caused the v3.5.0-rc.2 `:compileReleaseKotlin` failure (`Unresolved reference 'HtmlToMarkdownRsBridge'`): `bridge_obj` filename is now used for trait-bridge codegen so the file matches the object name; trait-bridge emission is skipped when the bridge function is excluded via `kotlin_android.exclude_functions`. Also picks up the alef 0.19.5 cumulative sweep: WASM emitter JSON-deserializes structured sub-config fields; swift-bridge restores JSON deserialization step in pre-call AHashMap binding; alef-emitter removes stray `>` after `.collect::<Vec<Vec<String>>>()`; PHP/Ruby/Elixir/Swift/Dart bridges emit pre-call `AHashMap` binding + `ahash = "0.8"` scaffold dep for `Cow<'static, str>` key map params; WASM wraps sanitized `Vec<Vec<String>>` fields with `serde_wasm_bindgen::to_value()`; WASM deduplicates input DTO struct generation across functions sharing the same config type; FFI preserves `AHashMap<Cow<'static, str>, _>` param types across the wrapper boundary; setup-defaults-ruby appends `--add-checksums` to default `bundle install`; scaffold-ffi injects workspace version into every internal workspace dependency so `cargo publish` accepts the FFI crate.
* **ci(publish): replace inline Homebrew formula updater with `xberg-io/actions/publish-homebrew-source-formulas@v1`.** The `publish-homebrew-formula` job previously ran a 184-line `scripts/publish/update-homebrew-formula.sh` Bash heredoc that wrote `html-to-markdown.rb` + `libhtml-to-markdown.rb` from scratch (h2m is a dual-formula tap; the shared single-formula `publish-homebrew@v1` doesn’t apply). The new shared action does the same job from per-formula `.rb.tmpl` templates + a `scripts/publish/homebrew.json` manifest, downloading release assets via `gh release download` and substituting their SHA256s into `${cli_*_sha}` / `${ffi_*_sha}` placeholders. The script is deleted; the formula generation rules now live in version-controlled Ruby templates rather than a bash heredoc. The job’s gate now also passes on `dry_run == 'true'` (was `is_tag == 'true'` only) so dry-run pipelines exercise the bottle pipeline downstream — the new action substitutes a zero-SHA placeholder for missing assets on dry-run.
* **list**: Fix content duplication in Markdown output and the document structure collector when list items contain nested `ul` or `ol` children. `item.rs` previously captured the full rendered output of an `<li>` — including the rendered nested-list Markdown — as the item’s text. A `text_end_pos` cursor now advances only past non-list children, so the structure collector records only the item’s own text and the Markdown output for outer and mid items is not repeated. Affected: any `ul > li > ul` or `ol > li > ol` (arbitrarily nested) HTML structure. (#385)
* **ci(publish): skip `publish-hex` and `homebrew-bottles` on dry-run.** Both jobs need real GitHub Release assets (`generate-elixir-checksums` downloads NIF tarballs; `brew install --build-bottle` downloads CLI/FFI source tarballs), but `upload-release-assets@v1` only logs on dry-run — the release doesn’t exist. Both jobs failed every dry-run after surviving every other stage. Gated their `if:` on `dry_run != 'true'`; real-release runs continue to exercise them.
* **ci(publish): replace inline Elixir Hex packaging with `xberg-io/actions/build-elixir-hex@v1`.** The `elixir-package` job in `.github/workflows/publish.yaml` previously ran `mix deps.get` + `mix hex.build` inline with no path-dep rewrite and no `Cargo.lock` generation. `Cargo.lock` is gitignored, so on a fresh CI checkout `mix hex.build` failed at the `files` list check with `Missing files: native/html_to_markdown_nif/Cargo.lock` — the proximate blocker on v3.5.0-rc.2 dry-run after the Go FFI fix landed. The new shared action wraps `rewrite-native-deps@v1` (default-on, dry-run-guarded) and falls back to `cargo generate-lockfile` on dry-run so the lockfile exists for `mix hex.build` even when the rewrite is skipped. Hex source-package builds now match the python-sdist / ruby-gem pattern (rewrite baked into the shared action; cannot be omitted).
* **ci(publish): build the Go FFI matrix on dry-runs too.** `.github/workflows/publish.yaml` job `go-ffi-libraries` gated only on `release_go == 'true'` and the registry existence check, so on `workflow_dispatch` dry-runs it skipped entirely. Its downstream sibling `upload-go-release` already gates on `is_tag || dry_run` but waits for `go-ffi-libraries.result == 'success'`, so no Go assets were ever uploaded to the dry-run release, and the terminal `verify-assets` gate failed with `✗ pattern NOT matched: html-to-markdown-rs-go-*.tar.gz` on every recent retry (the immediate blocker on v3.5.0-rc.1 publish). Added the `(is_tag == 'true' || dry_run == 'true')` clause to `go-ffi-libraries`’s `if:`, mirroring the `kotlin-android-natives` pattern (precedent: commit `e00a56e1` “ci(publish): build Kotlin Android natives on dry_run too”).
* **ci(e2e): pin `erlef/setup-beam@v1.24.0`** (was `@v1.24` floating minor) to avoid silent action upgrades during the rc cycle.
* **ci(e2e/ruby): drop the explicit `python3 scripts/ci/ruby/vendor-core-crate.py` step from both ruby build jobs in `.github/workflows/ci-e2e.yaml` (committed earlier today as `f23e6d458`); the dead script itself is removed in `f440af4fa`.** The shared `xberg-io/actions/build-ruby-gem@v1` action now invokes `rewrite-native-deps@v1` internally and vendors the core crate into `packages/ruby/vendor/html-to-markdown/` (no `-rs` suffix). Running the local script first wrote `packages/ruby/vendor/Cargo.toml` with `members = ["html-to-markdown-rs"]` and copied the crate into `vendor/html-to-markdown-rs/`; the subsequent action then created a sibling `vendor/html-to-markdown/` outside that members list, and cargo refused to build it with `error inheriting 'lints' from workspace root manifest's 'workspace.lints'` / `'workspace.lints' was not defined`. The action is now the single source of truth for ruby vendoring.
### Changed
[Section titled “Changed”](#changed-11)
* **ci(publish): pin `actions/checkout@v5` on the `homebrew-bottles` matrix job.** v6 hits an includeIf credential regression on the `macos-15-intel` runner that this matrix includes (same workaround liter-llm applies on its Homebrew matrix). Other jobs stay on `@v6`.
* **release: cut v3.5.0.** Promoted from v3.5.0-rc.3 after the dry-run/republish cycle (publish run 26393110006) reached fully green (31 success / 0 failed / 56 skipped). Aligned every workspace manifest on `3.5.0` via `alef sync-versions --set 3.5.0` + full `alef generate` regen.
* **release: cut v3.5.0-rc.1 release candidate.** Aligned every workspace manifest (Cargo + npm + PyPI + Maven + Composer + Gemfile + Hex + pub.dev + Zig + R + Cocoa + nuget + Cargo.lock entries) on `3.5.0-rc.1` via `alef sync-versions --set`. Refreshed every per-language dependency tree to its current upstream pin (`alef update --latest`) and re-generated all bindings, READMEs, docs reference pages, and e2e suites against alef 0.18.1 so the regen artefacts on disk match the version pin baked into every binding manifest.
* **bindings: regenerated with alef 0.19.2.** Picks up the cumulative v0.19.1 → v0.19.2 sweep: Swift codegen handles `serde_rename_all = "lowercase"` / `"UPPERCASE"` in unit enums and tagged Codable shapes (was silently emitting wrong casing); Swift now emits a custom Codable for serde-untagged data enums (the auto-derive previously used the wrong shape, surfacing as 19 runtime e2e failures); tagged-data enums route through `JSONDecoder` and `Vec<Codable-enum>` closure signatures are fixed. The trait-bridge codegen pipeline is rewired across all 14 language backends (rust/python/ts/node/wasm/ruby/php/go/c#/r/zig/elixir/dart/swift/java/kotlin-android) — super-trait lifecycle methods (`name` / `version` / `initialize` / `shutdown`) are driven by the IR instead of hardcoded literals, and canonical bridge-name helpers in Swift/Kotlin de-duplicate the prior near-misses. JNI no longer special-cases trait impl-name extraction; Kotlin Android accepts a `bridge_class_name` parameter so non-kreuzberg consumers (e.g. liter-llm) can opt out of the hardcoded `KreuzbergBridge` / `kreuzberg::` references. Java’s `package_dir` output_paths override now excludes setup/test/lint runs from `.../src/main/java/` so they execute from `packages/java/` as expected; JNI 0.22 compatibility was tightened (`RuntimeMethodSignature` parsing, borrow semantics, unsafe-block scoping, `JString` lifetime binding). Inherited from the v0.19.1 fix landed earlier today: magnus (Ruby) and rustler (Elixir) `NodeContent::MetadataBlock` reverse conversion now reconstructs `Vec<(String, String)>` from the sanitized `Vec<Vec<String>>` binding shape (the prior code didn’t type-check and broke every Ruby build).
* **bindings: regenerated with alef 0.18.1.** Picks up the v0.18.0 → v0.18.1 sweep: Java Builder `#[serde(default)]` non-optional fields use boxed nullable types so omitted JSON keys survive Jackson round-trip; PHP enum-variant accessor paths skipped before field validation; Python pyproject TOML arrays normalised to canonical `pyproject-fmt` shape; the Windows e2e runner no longer clobbers the inherited `Path` (case-insensitive env-key collision on `std::process::Command::env`); Ruby scaffold emits a `Steepfile` that ignores `lib/<gem>/native.rb` so Steep stops tripping on the Sorbet sigs the magnus backend deliberately emits; `alef readme` markdown normalisation matches `rumdl-fmt` MD012 (one blank max) so cold-regen READMEs no longer diverge from the `alef all` output; rubocop double-quote / `%w[...]` defaults emitted directly; Kotlin Android `.gitkeep` is empty (matches `end-of-file-fixer`); WASM optionalised non-Duration fields preserve core `Default` via the if-let wrapper; `Box<str>` round-trips through binding `String` via the new `CoreWrapper::Box` classifier; bare `str` resolves to `TypeRef::String` instead of falling through `sanitize_type_ref`; Zig test preamble installs `SIG_IGN` on `SIGABRT` so C++ destructor `abort()`s don’t break the test-runner IPC; Java sealed-interface tagged-enum field defaults emit `new EnumName.Variant()` (records can’t be statically referenced); PHP binding structs with custom core `Default` suppress the auto `#[derive(Default)]` and emit a delegating `impl Default`; doc-test import paths use the published crate name `alef` (post workspace-collapse); kotlin-android snapshot updated for vanniktech 0.36 (`SourcesJar.Sources()`, no-arg `publishToMavenCentral()`); Java e2e resolves per-fixture mock URLs from system properties; Java `Vec<T>`/`Map<K,V>` marshaling uses `MAPPER.writerFor(constructCollectionType(...))` to preserve `@JsonTypeInfo` discriminators; PyO3 `_to_rust_*_config` aliases serde-renamed keys + final pyo3 calls use serde-renamed param names.
* **bindings: regenerated with alef 0.18.0.** Workspace collapse + 0.17.36 → 0.18.0 cumulative codegen sweep. Notable fixes consumed in this regen: PyO3 `replace_constructor_with_serde_rename` skips the trait-bridge options field (`visitor`) from `sorted_fields` to avoid emitting it twice on `has_default` types with cfg-gated bridge fields (h2m all-features `ConversionOptions::new` previously failed `rustc E0415: identifier 'visitor' is bound more than once`); PHP e2e codegen sources the JSON key rename strategy from the language-effective `serde_rename_all` (camelCase by default) rather than the Rust core type’s (which is `None` for h2m’s `ConversionOptions`) so `from_json` reads the keys correctly into the binding struct’s `#[serde(rename_all = "camelCase")]` — fixes 32 / 7-error PHP e2e failures; `alef all` repopulates `current_gen_paths` from the e2e cache manifest on a cache hit so the orphan-cleanup pass does not delete every previously-generated e2e file (157 deletes observed on first warm run); `[crates.{node,wasm}.crate_dir]` per-language override lets h2m point alef at its actual `crates/html-to-markdown-{node,wasm}` Rust crate dirs (without the `-rs` infix that the default formula assumed).
* **package READMEs: regenerated with cold `alef readme`.** The 0.18.0 regen sweep used `alef all` whose hot-cache README pass omits the blank lines between consecutive `##` section headers that the standalone `alef readme` pass emits cold. CI’s `Validate READMEs` step (cold `alef readme`) caught the divergence; this commits the cold output. Same cosmetic alef bug as the prior `dcd072a58` patch; tracked separately upstream.
* **bindings: regenerated with alef 0.17.36.** Picks up the v0.17.18→v0.17.36 cumulative codegen sweep, including: Rustler `from_json` NIF shims gated on types with NIF wrappers (fixes Elixir NIF compile errors for `ConversionOptionsUpdate`, `PreprocessingOptionsUpdate`, `NodeContext`); Kotlin Android `= PreprocessingOptions()` synthesized defaults for non-nullable nested struct fields with Rust `Default` (fixes Jackson `MissingKotlinParameterException` on partial-options JSON, 98 → 0 failures); Kotlin sealed-class `@field:JsonSerialize(as = …)`/`contentAs` annotations; Kotlin `@JsonIgnoreProperties(ignoreUnknown = true)` + nullable default for `#[serde(flatten)]` fields; JNI `crate_suffix = "-jni"` build fix; Zig test_apps build.zig references binding `module_name` (not registry `pkg_name`) for `root_source_file`; Zig local-path dependencies in registry-mode test_apps; Dart pubspec single-caret version constraint; wasm `package.json` filenames use underscores (`html_to_markdown_wasm.js`); plus inherited 0.17.18-0.17.23 fixes (Swift visitor `case continue`, C# enum converters + nullable options, PHP `with_visitor` wither for trait-bridge fields, PyO3 streaming wrapper type identity, Go unresolved-Named fallback, Java sealed-interface display helpers, Ruby array literals, Dart positional-vs-named heuristic, R `.alef_format_value` wrapping, WASM camelCase input DTOs). Includes C visitor test suite (208 → 262 tests). The v0.17.25→v0.17.27 increment additionally brings: Rustler opaque-type NIF resource wrappers and enum-variant-field type collection (fixes `cannot find type` errors for types reachable only through enum variants); Kotlin Android `LongMethod` added to the generated `@file:Suppress` list, trait-interface emission skipped (no `IDocumentExtractor`/`IRenderer` redeclaration), `Vec<u8>` return types mapped to `ByteArray`, and integer-like float literals normalized; Java `null` (not `""`) builder default for `Path` fields and streaming adapters skipped; PHP `#[php(name = …)]` on facade static methods; Swift `unwrap_or` instead of `unwrap_or_else` in serde fallbacks (clippy `-D warnings`); WASM stops emitting the broken `*Input` config DTO; and the extractor skips underscore-prefixed `pub fn`s (test-only helpers no longer leak into bindings or docs). The v0.17.28→v0.17.32 increment additionally brings: C FFI struct-field getters for nested struct and `Option<T>` fields now return a cloned, boxed value instead of `null` (`htm_html_metadata_document`, `htm_conversion_result_document`, `htm_conversion_result_metadata`); the Node `index.d.ts`/`index.js` are emitted by NAPI-RS at build time and no longer carry an alef generated-header; plus Swift visitor `VisitResult`, Java sealed-interface, and Ruby scaffold corrections. The v0.17.32→v0.17.34 increment additionally brings: a `LICENSE` file synced into every per-language package directory (pub.dev, RubyGems, and other registries require one); per-language READMEs that render only their own binding section instead of leaking every language’s bullet; the PHP e2e harness no longer re-execs PHP with `-n` (PHPUnit keeps shared modules); the Ruby scaffold’s `.rubocop.yml` excludes generated `lib/**/*.rb`; PHP streaming facade methods + snake_case adapter names; PyO3 keyword-escaping and signature defaults in serde-rename constructors; Java `clear_fn` `(int, String)` error constructor; and C/Zig/C# e2e codegen compile fixes. The v0.17.34→v0.17.35 increment additionally brings: PyO3 trait-bridge constructor signatures and dict-coercion exclude the synthetic bridge field (e.g. `visitor`) — fixes spurious `visitor=...` kwargs on generated Python constructors and stale dict round-trips; magnus RBS type aliases use lowercase identifiers (`json_value`) — invalid uppercase `JsonValue` was breaking `steep check`; ext-php-rs getters for `Option<NonOpaqueNamed>` explicitly `.map(Into::into)` instead of relying on the blanket `IntoZval` impl that did not unwrap the inner type; Dart e2e fixture codegen emits a default `ConversionOptions()` instance for absent required-positional options; Java `options_type` inherits from sibling language overrides; CLI `--version` syncs `packages/zig/build.zig.zon`; kotlin-android publishing switched to the vanniktech maven-publish plugin for Maven Central Portal. The v0.17.35→v0.17.36 increment additionally brings: the `/* serde(default) */` placeholder marker (used as a `required`-suppression flag for C#) is filtered before emission in `alef-codegen` and `alef-backend-java` — generated Java now contains `List.of()` / `false` / `0` instead of `/* serde(default) */`, and generated magnus Rust uses the type’s actual zero value (`vec![]` / `false`); kotlin-android `.editorconfig` disables ktlint’s `trailing-comma-on-call-site` and `-on-declaration-site` rules (ktfmt strips them, ktlint demands them — the two were fighting on `build.gradle.kts` after the vanniktech migration); brew unsupported-call `unsupported_in` configuration; csharp variant-struct payload type fix; alef-e2e elixir Rustler NifTaggedEnum tuple emission for tagged-enum array args; publish workflow orders `alef-scaffold` ahead of backends.
### Tests
[Section titled “Tests”](#tests)
* **Taskfile: add `dart:e2e`, `swift:e2e`, `zig:e2e`, `kotlin_android:e2e` convenience tasks** so all 16 language bindings have a uniform per-language local e2e entry point matching the existing `c:e2e` / `python:e2e` / `node:e2e` / etc. pattern. Each delegates to `alef test --e2e --lang <name>`; the previously-existing `e2e:test:<lang>` tasks (which run against the published-package `test_apps/` registry tree) stay alongside. Verified all 16 suites pass locally: c (262), csharp (262), dart (262), elixir, go, java, kotlin_android, node (262), php (262 — after the alef PHP rename fix), python (262), r (639), ruby (262), rust, swift (262), wasm (263), zig.
* **e2e/php: skip visitor fixtures in `fixtures/edge-cases/visitor_errors.json`** — five visitor fixtures (`visitor_custom_element_with_nesting`, `visitor_unknown_tag_preservation`, `visitor_deeply_nested_skip`, `visitor_element_start_skip_entire_subtree`, `visitor_element_end_modification`) now carry `"skip": { "languages": ["php"] }` matching the rest of the visitor fixtures already in `fixtures/visitor/*.json`. The PHP `ext-php-rs` binding does not yet support callable visitor handles (no `VisitorHandle::from_php_object()` method), so these tests were emitting unbuildable test code. Generated PHP tests dropped from 262 to 208; suite is fully green.
* **e2e/kotlin_android: build the JNI crate in the e2e before-hook** — the Kotlin/Android host-JVM e2e loads `libhtm_jni` (the `html-to-markdown-rs-jni` crate’s `[lib] name = "htm_jni"` cdylib), not the C FFI dylib. The `[crates.test.kotlin_android]` before-hook in `alef.toml` was building `html-to-markdown-ffi`, so all 208 tests failed with `UnsatisfiedLinkError: no htm_jni in java.library.path`. It now builds `html-to-markdown-rs-jni`; the suite is fully green.
* **e2e/node: invoke the napi build via `pnpm run build` in the e2e before-hook** — the `[crates.test.node]` before-hook ran a bare `napi build`, which is not on `PATH` in CI (the `@napi-rs/cli` binary lives in `node_modules/.bin`). The before-hook now runs `pnpm install && pnpm run build` so napi resolves from the crate’s own `package.json` `build` script, fixing `sh: 1: napi: not found`.
### Fixed
[Section titled “Fixed”](#fixed-28)
* **core: fix panic slicing output at a non-UTF-8 char boundary** — `paragraph.rs` captured `content_start_pos = output.len()` before appending a separator; a subsequent `output.pop()` in the whitespace-normalisation path of `handle_span` could shift the effective boundary one byte back, landing it mid-codepoint (e.g. inside U+25A0 ■). The structure-collector slice `output[content_start_pos..]` then panicked. Fixed by clamping with `floor_char_boundary` before slicing; the same clamp is now applied at the two analogous sites in `figure.rs`. Triggered by `include_document_structure = true` with a `<pre>` preceding block and a `<span>` whose first character is multibyte. (#380)
* **core: avoid stack overflow on documents with many unclosed list items** — preprocessing now applies the HTML5 implicit-close rule for `<li>`, `<dt>`, and `<dd>` before the `tl` parser sees the document, so a 15k-item changelog with bare `<li>` tags (e.g. `https://curl.se/changes.html`) is parsed as siblings instead of a 448-deep chain. Eliminates a process abort (`fatal runtime error: stack overflow`) that bypassed `Result::Err` and `std::panic::catch_unwind`. (#379)
### Documentation
[Section titled “Documentation”](#documentation)
* **install: Windows MSVC linker / PATH troubleshooting** — `docs/installation.md` and the per-package Python READMEs now document `pip install --only-binary=:all: html-to-markdown` and how to keep MSVC’s `link.exe` ahead of GNU/Cygwin `link` on `PATH` when sdist fallback is unavoidable. (#378)
* **wasm: `NodeContent::MetadataBlock { entries }` round-trips correctly as `[[k,v],...]`** — the `entries: Vec<(String, String)>` field is now stored as `JsValue` in the wasm binding struct and serialized/deserialized via `serde_wasm_bindgen` instead of `Vec<String>`, preserving the nested-array wire format that serde produces for tuple vecs.
### Added
[Section titled “Added”](#added-4)
* **`compact_tables` option** — set `compact_tables: true` on `ConversionOptions` to emit GFM tables with no column padding. Cells are flushed to content width and separator rows use exactly `---` per column, producing token-efficient output for RAG / LLM pipelines. Default `false`; existing output is unchanged.
* **Kotlin Android binding** — `dev.kreuzberg:html-to-markdown-android` on Maven Central. Standalone Android library (AAR) with bundled `libhtml_to_markdown_ffi.so` for `arm64-v8a` and `x86_64` ABIs; minSdk 21, compileSdk 35. JVM Kotlin users continue to consume the existing Java package (`dev.kreuzberg:html-to-markdown`) directly — Kotlin/JVM treats Java classes as native and Panama FFM is unavailable on Android, which is why Android needs its own package.
* **Swift binding** — `HtmlToMarkdown` Swift Package on Swift Package Index. SPM-only (no CocoaPods); macOS 13+, iOS 16+; powered by `swift-bridge`.
* **Dart binding** — `h2m` on pub.dev. Built with `flutter_rust_bridge` 2.12; supports Flutter Android/iOS targets plus server Dart on Linux/macOS/Windows. Package name `h2m` because `html_to_markdown` and `html-to-markdown` are taken on pub.dev.
* **Zig binding** — published via GitHub Releases (`build.zig.zon` + tarball SHA-256 in release notes). Requires Zig 0.16+; links the existing `html_to_markdown_ffi` C library — no separate Rust bridge crate.
* **ffi**: `htm_visitor_handle_from_callbacks` exports a vtable-style visitor-handle constructor for zig and other C consumers. Wraps a `HtmVisitorCallbacks` struct into the `VisitorHandle` shape expected by `htm_conversion_options_builder_visitor`.
## \[3.4.1] - 2026-05-13
[Section titled “\[3.4.1\] - 2026-05-13”](#341---2026-05-13)
### Changed
[Section titled “Changed”](#changed-12)
* **core**: `ConversionOptions` is now `Send + Sync`. `VisitorHandle` switched from `Rc<RefCell<dyn HtmlVisitor>>` to `Arc<Mutex<dyn HtmlVisitor + Send>>`, allowing `ConversionOptions` to be stashed in axum/tokio/rmcp `Send`-bound contexts. Bindings update bridge constructors to use `Arc::new(Mutex::new(...))` and add `unsafe impl Send + Sync` where required (NAPI, WASM, Magnus, FFI visitor structs).
### Fixed
[Section titled “Fixed”](#fixed-29)
* **R: `convert(html, options)` no longer rejects `ConversionOptions$default()` and `ConversionOptions$builder()$build()`.** The extendr wrappers return an `ExternalPtr<ConversionOptions>`, not an R named list, so `decode_options` raised `"options must be a named list"` for every call that used the convenience constructors. `decode_options` now extracts the wrapper directly before falling back to list decoding.
* **C#: `[DllImport("html_to_markdown_ffi")]` resolves under `ProjectReference` consumption.** P/Invoke only searches the assembly directory and standard `DYLD`/`LD_LIBRARY` paths, not NuGet’s `runtimes/<RID>/native/` layout, so e2e and any other ProjectReference-based test project failed with `DllNotFoundException`. `packages/csharp/HtmlToMarkdown/HtmlToMarkdown.csproj` now copies the host-RID native library flat alongside the assembly via `<Content Include="runtimes/$(NETCoreSdkRuntimeIdentifier)/native/*" Link=… />`. NuGet consumers continue to pick it up from the existing `<None Include="runtimes/**" />` pack.
* **C#: CS0579 “Duplicate `AssemblyTitleAttribute`” eliminated.** The SDK auto-synthesises `AssemblyInfo` from `<PropertyGroup>`, which collided with checked-in `Properties/AssemblyInfo.cs` files. All three csproj files now set `<GenerateAssemblyInfo>false</GenerateAssemblyInfo>` and ship explicit `Properties/AssemblyInfo.cs`.
* **PHP: visitor `Custom` outputs preserve case for custom element callbacks** ([#2b54751a](https://github.com/xberg-io/html-to-markdown/commit/2b54751a)).
* **PHP: PIE binary discovery on macOS/Linux** ([#2b54751a](https://github.com/xberg-io/html-to-markdown/commit/2b54751a)).
* **Docs: `extract_metadata` description clarified to note it only gates the metadata pass** — table extraction into `result.tables` still runs unconditionally ([#4ba2187a](https://github.com/xberg-io/html-to-markdown/commit/4ba2187a)).
## \[3.4.0] - 2026-05-09
[Section titled “\[3.4.0\] - 2026-05-09”](#340---2026-05-09)
### Added
[Section titled “Added”](#added-5)
* **Homebrew distribution** for `html-to-markdown` (CLI) and `libhtml-to-markdown` (FFI library + headers + pkg-config + CMake configs). Pre-built tarballs for macOS arm64/x86_64 and Linux arm64/x86_64; install with `brew install xberg-io/tap/html-to-markdown`.
* **WASM bundles** for all four wasm-pack targets (`web`, `bundler`, `nodejs`, `deno`) under `@kreuzberg/html-to-markdown-wasm`.
* **C# NuGet package** `KreuzbergDev.HtmlToMarkdown` with native runtimes for linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64, win-arm64.
* **Java Maven Central package** `dev.kreuzberg:html-to-markdown` bundling native libraries for the same six platforms via `META-INF/native/<rid>/`.
* **Elixir Hex package** with `rustler_precompiled` NIFs for Linux + macOS (NIF 2.16/2.17 × 3 platforms); released artifacts download at first run.
* **PHP PIE pre-built archives** for PHP 8.2/8.3/8.4/8.5 × 6 platforms — `pie install xberg-io/html-to-markdown-rs` no longer requires building from source.
* **CLI panic guard** — conversion failures inside the CLI now surface as actionable errors via `panic::catch_unwind` instead of partial output + Rust backtrace.
* **`HtmlVisitor` parity across all bindings** — Python, Node/TypeScript, Ruby, PHP, Go, Java, C#, Elixir, R, and WASM all expose the visitor interface with `visit_element_start`/`visit_text`/`visit_element_end` and `VisitResult::{Continue, Skip, Custom}` semantics matching the Rust core.
* **Polyglot codegen via [alef](https://github.com/xberg-io/alef)** — bindings, e2e tests, and READMEs for all 11 target languages are generated from a single `alef.toml` + Rust source of truth, eliminating drift across the polyglot surface.
### Fixed
[Section titled “Fixed”](#fixed-30)
* **#348 — `OutputFormat::Plain` ignored `HtmlVisitor` callbacks.** The plain-text walker (`crates/html-to-markdown/src/converter/plain_text.rs`) ran the markdown pipeline first, then discarded its output and re-traversed the DOM via a visitor-less `walk_plain`, so `VisitResult::Custom`/`Skip` returned from `visit_element_end`/`visit_text` was silently dropped for `Plain`. Threaded a `WalkState` carrying the visitor through the plain walker so element/text hooks fire and their results are honoured.
* **#347 — `<img src>` URLs not escaped, breaking CommonMark round-trip.** `crates/html-to-markdown/src/converter/handlers/image.rs` emitted `src` raw, while `<a href>` already wrapped spaces/parens in angle brackets. Image renderer now uses the same three-branch escaping as links: empty → `<>`, contains space/newline → `<URL>`, unbalanced parens → `\(`/`\)` escaping.
* **#336 — large MS Word HTML truncated when `<td><p class='MsoNormal'>…</td>` appears as the leading cell.** The `tl` parser absorbs subsequent `<td>` and document content into the unclosed `<p>`, nesting the rest of the DOM inside the first table cell. Extended `has_inline_block_misnest` in `converter/preprocessing_helpers.rs` with a `has_p_ancestor` check that detects `td`/`tr`/`th` under `<p>` (structurally impossible in valid HTML) and triggers the existing html5ever repair path.
* **Split closing tags `</tagname\n>` corrupted DOM and dropped content.** JSX-style HTML (closing-tag `>` on the next line) caused the `tl` parser to leave elements unclosed, which silently absorbed siblings and dropped entire sections — affecting #127 (MW841 product headings missing from multilingual page), #143 (word-wrap merging nested link list items), and #121 (SPA menu nesting). New `normalize_split_closing_tags` preprocessing pass collapses such patterns to `</tagname>` before parsing, wired into all four preprocessing branches in `converter/main.rs`.
* **Tables now emit padded, aligned columns.** Each cell is padded to the widest cell in its column; the separator row uses `max(3, col_width)` dashes per column. `*` and `_` are escaped in table cells regardless of `escape_misc`. Fixes the gh-140 fixture parity and produces CommonMark-conformant tables out of the box.
* **#339 — bogus HTML comment endings dropped following content.** The `astral-tl` parser silently discarded every byte after `<!-- /// --->` or any `--[-]+>` comment terminator. New `normalize_bogus_comment_endings` preprocessing pass rewrites such sequences to `-->` before parsing; wired into the html5ever-repair and inline-block-misnest fallback paths too.
* **#340 — npm pre-release versions clobbered the `latest` dist-tag.** Pre-release versions (matching `-(rc|beta|alpha|pre|dev)`) now publish under the `next` dist-tag, so `pnpm add @kreuzberg/html-to-markdown-node` no longer pulls a 3.4.0-rc over a stable 3.3.x.
* **#337 — `from html_to_markdown import HeadingStyle` raised `TypeError`.** The package now re-exports the native PyO3 enums directly from `_html_to_markdown` and adds uppercase aliases (`HeadingStyle.ATX`, `CodeBlockStyle.BACKTICKS`) so both naming conventions satisfy `ConversionOptions(heading_style=…)`.
* **#334 — Ruby `HtmlToMarkdown.convert(html, options)` raised `TypeError` on every call with options.** The wrapper passed a `ConversionOptions` object to the FFI, but the generated Rust function expects `Option<String>` JSON. Wrapper now serialises the options hash to JSON before crossing the FFI boundary.
* **#332 — `default-features = false` Rust build broken.** Bare `#[serde(...)]` and `#[derive(Serialize, Deserialize)]` on core types in `src/types/{document,tables,result,warnings}.rs` and `src/options/conversion.rs` are now feature-gated behind `#[cfg_attr(feature = "serde", ...)]`. CI now runs a `cargo check --no-default-features` matrix to prevent regressions.
* **#331 — visitor `element_start`/`element_end` events mispaired for hyphenated/namespaced custom tags.** The `repair_with_html5ever` fallback re-parsed under HTML5 semantics, which discard XML-style self-closing on unknown elements. The repair path now pre-expands XML self-closing tags on non-void elements to explicit open+close pairs before the HTML5 parse.
* **PHP visitor marshaling** — visitor callbacks now correctly marshal arguments and handle array return values; `setVisitor()` method added to `ConversionOptions`.
* **Elixir metadata serialization** — metadata maps now serialize as JSON instead of Elixir debug format.
* **WASM Vitest environment** — WASM module loading now correctly handles Node.js module format in Vitest test environments.
* **R e2e result wrapping** — `result_is_r_list` configured to suppress `jsonlite` double-wrapping of conversion results.
### Changed
[Section titled “Changed”](#changed-13)
* **pnpm v11** — migrated from pnpm v10 to v11; `pnpm-workspace.yaml` declares `onlyBuiltDependencies: [esbuild]` and `ignoredBuiltDependencies: [wasm-pack]` for the new opt-in build script policy.
* **Cross-language dependency bumps** — `org.jetbrains:annotations` 26.0.0 → 26.1.0, plus updates across all language toolchains via `task upgrade`.
## \[3.3.3] - 2026-04-23
[Section titled “\[3.3.3\] - 2026-04-23”](#333---2026-04-23)
### Fixed
[Section titled “Fixed”](#fixed-31)
* **Python enum KeyError** (#324) — `ConversionOptions()` with default enums no longer crashes; PyO3 enum fields are passed directly instead of broken `str()` + map lookup.
* **Ruby Magnus binding** — fixed 65 compilation errors: `funcall` API, visitor bridge args, `Vec` conversion, optional flattening, sanitized field serde round-trip.
* **Elixir `.formatter.exs`** — 120-char line length, generated code now passes `mix format --check-formatted`.
* **Unused deps** — removed `serde_json` from Node and WASM binding crates.
* **Checkstyle** — excluded `test_apps/` from pre-commit checkstyle hook.
## \[3.3.2] - 2026-04-23
[Section titled “\[3.3.2\] - 2026-04-23”](#332---2026-04-23)
### Fixed
[Section titled “Fixed”](#fixed-32)
* **Elixir visitor bridge** — implemented async thread-based visitor protocol using `rustler::thread::spawn` + `OwnedEnv::send_and_clear` + `mpsc` channels, replacing the impossible synchronous `env.call()` approach.
* **Elixir NIF rustler 0.37** — replaced removed `SavedTerm`, `is_nil()`, `Pid::spawn_monitor`, `.encode()` APIs with 0.37-compatible equivalents.
* **Elixir type conversions** — fixed double-optional wrapping (`map(Some)`) and ambiguous `From` impl in generated `_from` methods.
* **Java checkstyle** — added `maven-checkstyle-plugin` to pom.xml pointing to project `checkstyle.xml` (120-char limit), so `mvn checkstyle:check` uses our config instead of default Sun checks.
* **Ruby Rakefile** — explicit `Bundler::GemHelper.install_tasks name:` for Bundler 4 compatibility.
## \[3.3.1] - 2026-04-23
[Section titled “\[3.3.1\] - 2026-04-23”](#331---2026-04-23)
### Fixed
[Section titled “Fixed”](#fixed-33)
* **Java checkstyle** — switched to 120-char line limit, added Spotless auto-formatting with Eclipse JDT formatter, added `final` params and javadoc to all generated code.
* **Elixir `list` type collision** — `NodeContent::List` variant no longer redefines Elixir’s built-in `list/0` type (now emits `list_variant`).
* **Elixir NIF missing `serde`** — added `serde` with derive feature as direct dependency to the NIF crate.
* **C# `VisitResult.Continue`** — default visitor methods now use `new VisitResult.Continue()` instead of non-invocable `VisitResult.Continue()`.
* **Node `convert` export** — restored the missing `#[napi] pub fn convert` function dropped during binding regeneration.
* **Ruby CI** — updated Bundler from 2.7.2 to 4.0.3 to match `Gemfile.lock`.
## \[3.3.0] - 2026-04-23
[Section titled “\[3.3.0\] - 2026-04-23”](#330---2026-04-23)
### Added
[Section titled “Added”](#added-6)
* **`exclude_selectors` option** — CSS selector-based element exclusion. Unlike `strip_tags` (which removes the wrapper but keeps children), excluded elements and all descendants are dropped entirely. Supports any CSS selector: `.class`, `#id`, `[attribute]`, compound selectors. Works in both markdown and plain text output modes.
* **CLI flags** — `--preserve-tags`, `--skip-images`, `--max-depth` for full ConversionOptions parity.
* **Visitor pattern for all bindings** (#314, #313) — restored visitor support across Python, TypeScript, Ruby, PHP, Go, Java, C#, Elixir, R, WASM, and C FFI.
* **R visitor support** — added visitor callbacks for the R binding.
* **E2E test fixtures** — 78 new fixtures for 100% ConversionOptions field coverage (35/35 fields). Added fixtures for `exclude_selectors`, `ConversionResult.tables`, and `ConversionResult.warnings`.
* **Ruby RBS type stubs** — auto-generated via alef from the Rust IR, including `VERSION` constant. Gemspec now includes `sig/**/*`.
* **Alef pre-commit hook** — `alef-verify` hook added to `.pre-commit-config.yaml` to check generated code freshness. CI installs alef v0.5.3 binary.
### Fixed
[Section titled “Fixed”](#fixed-34)
* **`<h1>` inside `<header>` not exported** (#321) — top-level `<header>` elements were unconditionally dropped during preprocessing; now only `<header>` with navigation hints (e.g. `class="site-header"`, `role="navigation"`) is removed.
* **`PreprocessingPreset` not wired into preprocessing logic** — the `preset` field on `PreprocessingOptions` was defined but never checked. Now Minimal/Standard/Aggressive presets have distinct behavior.
* **`remove_forms` flag was dead code** — `<form>` elements are now dropped when `remove_forms: true` and preset is Standard or Aggressive.
* **Aggressive preset** — now drops navigation-hinted elements of any tag type, `<noscript>` elements, and noise-hinted elements (cookie banners, ad containers).
* **Python `NodeContent` type** — binding wrapper now implements `Default`, `Serialize`, `Deserialize` via forwarding to core type, fixing compilation when `DocumentNode` (which contains `NodeContent`) derives these traits.
* **Python `dict[str, Any]` for data enums** — `NodeContent`, `AnnotationKind`, `VisitResult` now use TypedDicts with `Literal` discriminators instead of untyped dicts.
* **Python `__init__.py` exports** — all public types now exported from the package.
* **`ImageMetadata.dimensions`** — tuple type `(u32, u32)` correctly maps to `Vec<u32>` / `number[]` / `[]uint32` in all bindings via serde round-trip conversion.
* **FFI doc comments** — multi-line doc strings on VTable struct fields now properly prefixed with `///` on every line (was breaking `cargo fmt`).
* **FFI optional parameters** — visitor methods with optional string params (`title`, `id`, `lang`) correctly generate `Option<&str>` instead of `&str`.
* **FFI duplicate imports** — removed duplicate `use std::ffi::...` in trait bridge output.
* **Go `htm_convert` stub** — FFI function was always returning “Not implemented”; now delegates to `core::convert(html, options, None)`.
* **Go lint errors** — fixed CGO preamble types, removed invalid `?` syntax, fixed parameter syntax, `NodeType` mapping, variable shadowing, gofmt indentation.
* **Java FFI broken on all platforms** (#315) — native libraries were bundled under wrong JAR path.
* **Java/C# visitor type conflicts** — fixed by skipping gen_bindings types when visitor bridge is active.
* **Ruby `convert()` TypeError** (#319) — options type mismatch and wrong return type.
* **PHP binding panics** — `from_update` and `from` methods now emit safe return values instead of `panic!()`.
* **R `ConversionOptionsBuilder`** — fixed placeholder panics in opaque type delegation.
* **CLI `autolinks` default** — replaced `--autolinks` with `--no-autolinks` so defaults match library.
* **CLI dead metadata flags** — removed flags that were parsed but never wired through.
* **Python 3.14 wheels** (#322) — enabled `abi3-py310` stable ABI for PyO3 crate, so a single wheel works on Python 3.10 through 3.14+ without per-version builds.
### Changed
[Section titled “Changed”](#changed-14)
* **Public API surface restricted** — internal Rust modules changed from `pub` to `pub(crate)`. API docs now document only the public API (down from 233 to 66 items).
* **alef.toml simplified** — switched from 20-item include whitelist to minimal 3-type + 1-function include. Transitive dependencies expand automatically.
* **Generated code lint-clean** — all generated bindings pass their respective language linters (`cargo fmt`, `cargo clippy`, `mypy`, `ruff`, `gofmt`, `dotnet format`, `mix format`, `steep check`, `rubocop`, `phpstan`, `biome`).
* **Dead code removed** — deleted unused dispatch functions, duplicate text utilities, and unused safety module from core crate.
* **CI consolidated** (#317) — 13 workflows merged into single `ci.yaml`.
## \[3.2.6] - 2026-04-20
[Section titled “\[3.2.6\] - 2026-04-20”](#326---2026-04-20)
### Fixed
[Section titled “Fixed”](#fixed-35)
* **Python type mismatch** — `convert()` return type annotation now uses the public `ConversionResult` instead of `_rust.ConversionResult`, fixing Pylance type errors when annotating with the re-exported type (#310).
* **Maturin build failure** — removed `readme = "README.md"` from binding crate Cargo.toml files (ffi, node, php, py, wasm) since no README exists for these internal crates (#309).
### Changed
[Section titled “Changed”](#changed-15)
* **PHPUnit** — bumped from `^12.5` to `^13.1` across root, e2e, and test_apps.
* **Pre-commit shfmt hook** — fixed rev from non-existent `v3.14.2-1` to `v3.9.0-1`.
* **Pre-commit ai-rulez hook** — updated from `v3.14.0` to `v3.14.2`.
## \[3.2.5] - 2026-04-18
[Section titled “\[3.2.5\] - 2026-04-18”](#325---2026-04-18)
### Fixed
[Section titled “Fixed”](#fixed-36)
* **Silent truncation on large HTML inputs** (#277) — fixed preprocessing pipeline gap where `strip_script_and_style_tags` was not called after `repair_with_html5ever`, causing documents with custom elements and scripts containing literal `<script>` strings to be silently truncated. Also fixed `preprocess_html` fallback to skip only the problematic tag instead of consuming the rest of the document.
* **WASM plain-object options** (#303) — WASM package now exports a wrapper `convert()` function that accepts plain JavaScript objects for options, eliminating the need to construct `WasmConversionOptions` class instances. The raw WASM classes remain available for advanced use.
### Added
[Section titled “Added”](#added-7)
* **`max_depth` option** — new `max_depth` field on `ConversionOptions` to limit DOM traversal depth, preventing stack overflow on deeply nested or malicious HTML. Default is `None` (unlimited). When set, subtrees beyond the limit are silently truncated.
### Removed
[Section titled “Removed”](#removed)
* Phantom type references (`MetadataResult`, `HeadingInfo`, `LinkInfo`, `ImageInfo`) from alef configuration that did not correspond to any Rust types.
## \[3.2.4] - 2026-04-17
[Section titled “\[3.2.4\] - 2026-04-17”](#324---2026-04-17)
### Fixed
[Section titled “Fixed”](#fixed-37)
* **Elixir Hex package** — fixed precompiled NIF pipeline: correct build output paths, removed Rust source from Hex files list, removed Windows target (no build job), simplified build script for `rustler_precompiled`.
* **C# NuGet package** — republished with `htm_conversion_options_from_json` and related FFI functions.
## \[3.2.3] - 2026-04-17
[Section titled “\[3.2.3\] - 2026-04-17”](#323---2026-04-17)
### Fixed
[Section titled “Fixed”](#fixed-38)
* **Java/C#/Go FFI functions** — `htm_conversion_options_from_json`, `htm_preprocessing_options_from_json`, and related `to_json` functions now generated. Fixed alef IR extraction to detect serde derives inside `#[cfg_attr(...)]` attributes.
* **Node.js native binding loader** — regenerated `index.js` with correct NAPI platform-aware loader (was referencing old `html-to-markdown-rs.node` binary name).
* **Go module path** — fixed from non-existent `github.com/xberg-io/html-to-markdown-go` to monorepo path `github.com/xberg-io/html-to-markdown/packages/go/v3`.
* **Elixir precompiled NIFs** — switched from `Rustler` (compile-from-source) to `RustlerPrecompiled` with CI jobs for building and uploading platform-specific NIF binaries to GitHub releases.
### Removed
[Section titled “Removed”](#removed-1)
* Stale hand-written test files superseded by alef-generated e2e tests (comprehensive_test, feature_test, smoke_test duplicates across Go, Python, Ruby, PHP, Node, WASM, Elixir, R).
* Empty placeholder crate directories (`html-to-markdown-rs-ffi`, `html-to-markdown-rs-wasm`).
* Duplicate Ruby extension directory (`html-to-markdown_rb` with wrong naming).
## \[3.2.2] - 2026-04-16
[Section titled “\[3.2.2\] - 2026-04-16”](#322---2026-04-16)
### Fixed
[Section titled “Fixed”](#fixed-39)
* **Ruby binding compilation** — fixed serde derive errors and Default trait conflicts by conditionally deriving serde traits only when all field types support it, and generating Default derives for kwargs constructors.
* **Ruby deprecated Magnus API** — replaced `magnus::exception::type_error()` / `runtime_error()` with `Ruby::exception_type_error()` / `Ruby::exception_runtime_error()` (Magnus 0.7+ API).
* **PHP e2e tests** — fixed missing class import causing “Class not found” fatal error.
* **Cargo.toml metadata** — added missing `readme`, `keywords`, `categories`, `description` fields to binding crate Cargo.toml files.
* **C# dotnet format** — auto-formatted generated C# bindings.
## \[3.2.1] - 2026-04-16
[Section titled “\[3.2.1\] - 2026-04-16”](#321---2026-04-16)
### Fixed
[Section titled “Fixed”](#fixed-40)
* **Node.js Docker/cross-platform installs** (#273) — platform-specific native packages (`@kreuzberg/html-to-markdown-node-linux-x64-gnu`, etc.) are now correctly published with `optionalDependencies` via NAPI prepublish, resolving cross-platform lockfile issues.
* **Homebrew formula** (#304) — formula updated with correct source tarball SHA and bottle configuration.
* **Ruby gem build failure** — fixed `NodeContent::MetadataBlock` type mismatch (`Vec<(String, String)>` → `String`) in binding-to-core conversion by deserializing sanitized fields from JSON.
* **Maven Central publish** — aligned `pom.xml` with kreuzberg: GPG plugin in main build section, developer email, correct `groupId` (`dev.kreuzberg`), `pluginManagement` with pinned plugin versions.
* **All binding compilation failures** — fixed private module path (`convert_api`) in generated bindings, missing `From` impls for function return types, glob import conflicts in PyO3/FFI backends, and cbindgen compatibility (removed `const extern fn`, updated to cbindgen 0.29).
* **Elixir NIF compilation** — added `compilers: [:rustler] ++ Mix.compilers()` to `mix.exs` so Rustler compiles the NIF during `mix compile`.
* **FFI `from_json`/`to_json` functions** — `htm_conversion_options_from_json`, `htm_conversion_result_to_json`, etc. now generated for all serde-compatible types, fixing Java (Panama FFM) and Go (cgo) bindings.
* **PHP e2e tests** — fixed function call generation to use correct `HtmlToMarkdownRs::convert()` pattern.
* **Python `pyproject.toml`** — corrected `module-name` and `python-packages` to match `html-to-markdown` pip package name.
* **`docs/llms.txt`** metadata defaults corrected from `false` to `true` for `extract_metadata`, `extract_document`, `extract_headers`, `extract_links`, `extract_images`, `extract_structured_data` (#276).
* **WASM type prefix restored** (#303) — `WasmConversionOptions` (not `JsConversionOptions`) via configurable `type_prefix` in alef. No breaking change for WASM users.
### Known Issues
[Section titled “Known Issues”](#known-issues)
* **Python silent output cap** (#277) — `convert()` silently truncates output at \~439 KB on certain large HTML inputs. Under investigation.
## \[3.2.0] - 2026-04-14
[Section titled “\[3.2.0\] - 2026-04-14”](#320---2026-04-14)
### Breaking Changes
[Section titled “Breaking Changes”](#breaking-changes)
#### Core Defaults Changed
[Section titled “Core Defaults Changed”](#core-defaults-changed)
* **`code_block_style`** default changed from `Indented` to `Backticks` — code blocks now use triple-backtick fences by default instead of 4-space indentation.
* **`bullets`** default changed from `"-"` to `"-*+"` — nested unordered lists now cycle through `-`, `*`, `+` at successive nesting levels.
* **`preprocessing.enabled`** default changed from `false` to `true` — HTML preprocessing (navigation removal, form stripping) is now on by default.
* **Rust serde field names** changed from `camelCase` to `snake_case` — affects JSON serialization/deserialization of the Rust core `ConversionOptions` struct (`heading_style` instead of `headingStyle`). Language bindings are not affected — each binding uses its language-native naming convention (camelCase for JS/TS/Java/C#, snake_case for Python/Ruby/Elixir/R).
#### Package Renames
[Section titled “Package Renames”](#package-renames)
* **TypeScript/Node.js**: npm package renamed from `@kreuzberg/html-to-markdown` to `@kreuzberg/html-to-markdown-node`.
* **PHP**: Namespace changed from `HtmlToMarkdown\` to `Html\To\Markdown\Rs\`. Main class renamed from `HtmlToMarkdown` to `HtmlToMarkdownRs`.
* **Java**: Maven coordinates remain `dev.kreuzberg:html-to-markdown`. Internal package namespace changed to `dev.kreuzberg.htmltomarkdown`.
* **C FFI**: Function prefix changed from `html_to_markdown_` to `htm_` (e.g., `htm_convert`, `htm_last_error_code`). Header moved to `include/html_to_markdown.h`.
* **C#**: Main class renamed from `HtmlToMarkdownConverter` to `HtmlToMarkdownRs`.
#### Python Exception Hierarchy
[Section titled “Python Exception Hierarchy”](#python-exception-hierarchy)
* Old exceptions (`HtmlToMarkdownError`, `EmptyHtmlError`, `InvalidParserError`, etc.) replaced with new hierarchy: `ConversionError`, `ParseError`, `SanitizationError`, `ConfigError`, `IoError`, `InvalidInputError`, `PanicError`, `OtherError`.
### Added
[Section titled “Added”](#added-8)
* **`ConversionOptionsBuilder`** is now public in the Rust API — use `ConversionOptions::builder()` for ergonomic option construction.
* **`TableData`** exported from crate root — no longer requires importing from submodules.
* **Per-language API reference documentation** — generated `docs/reference/api-{lang}.md` pages for Python, TypeScript, Go, Java, C#, Ruby, PHP, Elixir, WASM, and C with full type mappings, signatures, and docstrings.
* **Alef codegen** — all 12 language bindings (Rust, Python, TypeScript, Go, Java, C#, Ruby, PHP, Elixir, WASM, C, R) are now auto-generated from a single IR via [alef](https://github.com/xberg-io/alef), configured in `alef.toml`.
* **E2E test suite** — 130 fixture-driven tests across all 12 languages, generated from shared JSON fixtures in `fixtures/`.
* **`AnnotationKind`** and **`NodeContent`** now implement `Default`.
* **`ConversionResult`** now derives `Serialize`/`Deserialize`.
### Changed
[Section titled “Changed”](#changed-16)
* **Docs platform**: Switched from MkDocs to [Zensical](https://zensical.dev) (`zensical.toml` replaces `mkdocs.yaml`).
* **READMEs**: Now generated by `alef readme` from minijinja templates with inline configuration in `alef.toml`.
* **Version sync**: `task version:sync` now uses `alef` binary for all operations (replaces `sync_versions.py`).
* **CI workflows**: Simplified to e2e-only testing per language — removed per-binding unit test jobs.
### Removed
[Section titled “Removed”](#removed-2)
* **`crates/html-to-markdown-bindings-common`** — shared bindings helper crate replaced by alef codegen.
* **`tools/e2e-generator`** — replaced by `alef e2e generate`.
* **`tools/snippet-runner`** — snippet validation removed.
* **`scripts/generate_readme.py`**, **`scripts/sync_versions.py`**, **`scripts/readme_filters.py`** — replaced by alef.
* **Hand-written binding code** — all per-language binding implementations replaced by alef-generated code.
### Fixed
[Section titled “Fixed”](#fixed-41)
* **Preserve metadata when using AST visitors** (#279).
* **`deny_unknown_fields`** added to serde option structs — invalid JSON fields now produce errors instead of being silently ignored.
* **Ruby e2e generator** — fixed camelCase→snake_case field name conversion.
* **WASM test options** — added missing `link_style` field.
# Changelog archive: 3.1.0–2.14.1
## \[3.1.0] - 2026-04-01
[Section titled “\[3.1.0\] - 2026-04-01”](#310---2026-04-01)
### Added
[Section titled “Added”](#added)
* **Reference-style links**: New `link_style` option (`"inline"` default, `"reference"`) renders links as `[text][1]` with numbered `[1]: url "title"` definitions appended at the end of the output. Supports URL+title deduplication, images (`![alt][1]`), and media elements (audio, video, iframe). Available across all bindings (Python, Node.js, WASM, PHP, CLI `--link-style`, FFI via JSON).
## \[3.0.2] - 2026-04-01
[Section titled “\[3.0.2\] - 2026-04-01”](#302---2026-04-01)
### Fixed
[Section titled “Fixed”](#fixed)
* **Structure collector in tables**: Suppressed `StructureCollector` calls for headings and lists inside table cells, preventing spurious document-structure nodes from table content.
* **Char boundary safety**: Fixed potential panics from slicing at non-UTF-8-char boundaries in `generate_id` hash truncation and list item text extraction.
* **Dead feature gates removed**: Cleaned up unused `document-structure` feature gates that were no longer wired to any Cargo feature.
* **Structure collector coverage**: Added missing `StructureCollector` calls for lists, images, and code blocks so document structure captures all block-level elements.
## \[3.0.1] - 2026-03-31
[Section titled “\[3.0.1\] - 2026-03-31”](#301---2026-03-31)
### Fixed
[Section titled “Fixed”](#fixed-1)
* **WASM TypeScript types**: `convert()` now returns typed `WasmConversionResult` instead of `any`. All `WasmConversionTable`, `WasmGridCell`, `WasmTableGrid`, `WasmConversionWarning`, and `WasmInlineImage` interfaces are now emitted in generated `.d.ts` files. Added missing options fields (`skipImages`, `outputFormat`, `includeDocumentStructure`, `extractImages`, `maxImageSize`, `captureSvg`, `inferDimensions`). Fixes #265.
* **Python type stubs**: Synced crate `.pyi` stub with package stub — added keyword-only (`*`) parameter markers and `visitor` parameter to `convert()`.
* **PHP type stubs**: Expanded PHPStan stubs with full `ConversionResult`, `ConversionOptions`, and all nested type shapes. Wired stubs into `composer.json` PHPStan config.
## \[3.0.0] - 2026-03-30
[Section titled “\[3.0.0\] - 2026-03-30”](#300---2026-03-30)
### Added
[Section titled “Added”](#added-1)
* **Single `convert()` API**: One entry point across all 12 language bindings returning `ConversionResult` with content, document, metadata, tables, images, and warnings.
* **`ConversionResult` type**: Structured result with `content` (markdown/djot/plain), `document` (optional `DocumentStructure`), `metadata` (`HtmlMetadata`), `tables` (grid-based), `images` (inline image data), and `warnings`.
* **`DocumentStructure`**: Structured document tree with flat node array, index-based parent/child references, and `TextAnnotation` for inline formatting.
* **Options support in all bindings**: Go, Java, C# now accept options. All generators wire fixture options into e2e tests.
* **GFM defaults**: Code blocks default to backtick fences (was indented). ATX headings remain default.
* **E2E contract validation**: Generators produce tests validating ConversionResult structure (metadata, tables, warnings) across all 12 languages.
* **New options**: `includeDocumentStructure`, `extractImages`, `maxImageSize`, `captureSvg`, `inferDimensions`, `outputFormat` (markdown/djot/plain).
* **`<q>` element**: Wraps content in quotation marks.
* **`<figure>`/`<figcaption>` elements**: Routed to semantic handler with caption separation.
* **`hidden` attribute**: Elements with `hidden` stripped before parsing.
### Changed
[Section titled “Changed”](#changed)
* **`convert()` returns `ConversionResult`** instead of `String` in all bindings (Go, Java, C#, Node, Python, PHP, Ruby, Elixir, R, WASM, C FFI).
* **`ExtendedMetadata` renamed to `HtmlMetadata`** across all crates and bindings.
* **Go `Convert()`** returns `*ConversionResult` with `Content`, `Metadata`, `Tables`, `Images`, `Warnings` fields. Accepts optional JSON options via variadic parameter.
* **Table data** uses grid-based schema (`TableGrid` with `GridCell`) instead of flat `cells [][]string`.
* **`serde(deny_unknown_fields)`** on `MetadataConfig`, `MetadataConfigUpdate`, `InlineImageConfigUpdate`.
* **Go 1.26**, golangci-lint\@latest.
### Removed
[Section titled “Removed”](#removed)
* **All `convert_with_*` functions**: `convert_with_metadata`, `convert_with_inline_images`, `convert_with_visitor` (standalone), `convert_with_tables`, `convert_with_async_visitor` removed from public API. Single `convert()` replaces all.
* **Async visitor**: Feature removed entirely (`async-visitor` Cargo feature, `AsyncHtmlVisitor` trait, async bridge/dispatch code).
* **Profiling**: All profiling infrastructure removed (8 binding crates, CI workflow, C tests, `start_profiling`/`stop_profiling` APIs).
* **Benchmarks**: All benchmark scripts and harness removed.
* **hOCR support**: Entire `hocr` module deleted. The `hocr_spatial_tables` option removed.
* **Python v1 compatibility**: `convert_to_markdown()` and `markdownify()` removed.
* **Redundant binding tests**: Tests covered by e2e generators removed from Python, Ruby, Elixir, R.
## \[2.30.0] - 2026-03-27
[Section titled “\[2.30.0\] - 2026-03-27”](#2300---2026-03-27)
### Deprecated
[Section titled “Deprecated”](#deprecated)
* **hOCR support**: The `hocr_spatial_tables` option and all hOCR-related APIs are deprecated and will be removed in v3. All hOCR functionality continues to work but emits deprecation warnings. This is the final v2 release.
### Fixed
[Section titled “Fixed”](#fixed-2)
* **PHP PHPStan CI errors**: Removed redundant `@var` annotations and `is_array()` runtime checks in `ExtensionBridge.php` that PHPStan flagged as always-true due to stub-defined return types. Removed redundant `array_values()` calls in `ConversionOptions.php` on properties already typed as `list<string>`. Updated PHPStan baseline count for callable invocations.
## \[2.29.0] - 2026-03-22
[Section titled “\[2.29.0\] - 2026-03-22”](#2290---2026-03-22)
### Added
[Section titled “Added”](#added-2)
* **`full` feature group**: Added a `full` feature to core crate and all binding crates (PHP, Python, Node, WASM, FFI, Elixir, bindings-common) that enables all available features. All bindings now default to `full`.
* **Dublin Core metadata extraction**: `DC.*` and `DCTERMS.*` meta tags now map to dedicated `DocumentMetadata` fields (title, description, author, keywords). Other DC/DCTERMS fields stored in `meta_tags` with `dc_`/`dcterms_` prefix.
* **Extended keyword variants**: Keywords now extracted from `news_keywords`, `citation_keywords`, `DC.subject`, `DC.keywords`, `DCTERMS.subject`, `subject`, `topic`, `category`, and `classification` meta tags.
* **`cargo-sort` pre-commit hook**: Added for consistent Cargo.toml key ordering.
* **`checkmake` pre-commit hook**: Added for Makefile linting.
* **`typescript-typecheck` pre-commit hook**: Added TypeScript type checking via `tsc --noEmit`.
* **`typecheck` npm script**: Added to `packages/typescript/package.json`.
### Fixed
[Section titled “Fixed”](#fixed-3)
* **Case-insensitive meta tag matching** ([#251](https://github.com/xberg-io/html-to-markdown/issues/251)): All meta tag name matching is now case-insensitive per the HTML spec. `<meta name="Keywords">` and `<meta name="DC.keywords">` are now correctly captured.
* **PHP `convertWithTables()` not found** ([#250](https://github.com/xberg-io/html-to-markdown/issues/250)): The `visitor` feature was not enabled by default in the PHP binding crate, causing `html_to_markdown_convert_with_tables` to be missing from the extension.
* **PHP binding defaults**: PHP crate now defaults to `["full"]` (was `["metadata"]`), enabling visitor support.
* **Python binding defaults**: Python crate now defaults to `["full"]` (was `[]`), enabling metadata, visitor, async-visitor, and inline-images.
* **PHPStan 2.x compatibility**: Fixed 40+ PHPStan errors from the 1.x→2.x upgrade (type narrowing, property access on mixed, redundant assertions). Added `--memory-limit=512M` to prevent OOM.
* **Makefile `test` target**: Added missing `.PHONY: test` target to FFI test Makefile.
### Changed
[Section titled “Changed”](#changed-1)
* **Pre-commit config aligned with kreuzberg**: Added `cargo-sort`, `checkmake`, `typescript-typecheck`. Updated `taplo-format` to exclude `Cargo.toml`. Excluded `Makefile.frag` from checkmake.
* **Cargo.toml formatting**: All workspace Cargo.toml files sorted via `cargo-sort`.
* **pyproject.toml formatting**: All pyproject.toml files formatted via `pyproject-fmt`.
## \[2.28.6] - 2026-03-20
[Section titled “\[2.28.6\] - 2026-03-20”](#2286---2026-03-20)
### Changed
[Section titled “Changed”](#changed-2)
* **Ruby gem vendoring**: Replaced bash+embedded-Python vendoring script with a standalone Python vendoring script adapted from kreuzberg, using `vendor/` directory instead of `rust-vendor/` for core crate vendoring.
* **Ruby gem build**: Added `build-native-gem.rb` for platform-specific pre-compiled gem builds, following kreuzberg patterns.
* **Pre-commit hooks**: Switched Ruby hooks (rubocop, rbs-validate, steep-check) from inline bash commands to task-based delegation matching kreuzberg.
* **Dependabot config**: Expanded from GitHub Actions only to full multi-ecosystem coverage (Cargo, pip, npm, bundler, composer, gomod, maven, nuget, mix).
* **Task update commands**: Aligned all language update tasks with kreuzberg’s comprehensive approach (outdated checks, aggressive updates).
* **C# update**: Switched from slow `dotnet list --outdated` Python script to `dotnet-outdated-tool` for faster dependency updates.
### Fixed
[Section titled “Fixed”](#fixed-4)
* **CI Validate shfmt failure**: Fixed `packages/r/configure.win` tab indentation to match shfmt 2-space requirement.
* **Java linting**: Added PMD plugin (3.28.0), JaCoCo coverage (0.8.14), and pinned checkstyle runtime (13.3.0). Bumped maven-compiler-plugin to 3.15.0, maven-surefire-plugin to 3.5.5, spotless to 3.4.0, central-publishing to 0.10.0.
### Updated
[Section titled “Updated”](#updated)
* **GitHub Actions**: Bumped `go-task/setup-task` from v1 to v2, `nick-fields/retry` from v3 to v4.
* **Dependencies**: Updated all language dependencies via `task update`.
## \[2.28.5] - 2026-03-19
[Section titled “\[2.28.5\] - 2026-03-19”](#2285---2026-03-19)
### Fixed
[Section titled “Fixed”](#fixed-5)
* **Table colspan parsing** ([#233](https://github.com/xberg-io/html-to-markdown/issues/233)): Fixed column count calculation to accurately use colspan values instead of incrementing by 1, and refined layout table heuristics to exempt simple data tables with colspans while correctly catching layout tables.
* **Ruby version.rb formatting**: Fixed missing space around `=` operator in `version.rb` that caused Rubocop lint failures in CI.
* **CI tooling alignment**: Aligned tooling and documentation with kreuzberg standards, fixing CI failures.
## \[2.28.4] - 2026-03-13
[Section titled “\[2.28.4\] - 2026-03-13”](#2284---2026-03-13)
### Fixed
[Section titled “Fixed”](#fixed-6)
* **Panic with cid image followed by italic paragraph** ([#222](https://github.com/xberg-io/html-to-markdown/issues/222)): Confirmed fix for panic (“byte index 53 is out of bounds of \`\`”) when converting HTML containing `cid:` image paragraphs followed by italicized text. This was resolved in v2.28.0 via the block_content_start bounds fix (#216, #217) and multi-byte UTF-8 character boundary fix (#218).
* **Ruby gem installation on macOS** ([#219](https://github.com/xberg-io/html-to-markdown/issues/219)): Confirmed fix for `Cargo.lock` missing from published gem causing `magnus` dependency load failure. Resolved in v2.28.3 with native platform gem builds.
## \[2.28.3] - 2026-03-10
[Section titled “\[2.28.3\] - 2026-03-10”](#2283---2026-03-10)
### Fixed
[Section titled “Fixed”](#fixed-7)
* **Java visitor FFI struct return type**: Fixed `IllegalArgumentException: Wrong method handle type` when using visitors in Java. The Panama FFI callback descriptors incorrectly used `JAVA_LONG` (8 bytes) as the return type instead of the actual `HtmlToMarkdownVisitResult` C struct (24 bytes: enum + 2 pointers). All 14 callback descriptors now use a proper `StructLayout` matching the C ABI.
* **Homebrew bottle tarball structure**: Fixed bottle tarballs missing the required `html-to-markdown/{version}/` prefix directory. Homebrew expects this prefix for proper cellar installation.
* **Ruby gem publishing**: Added native platform gem builds (`rake native gem`) alongside source gems so precompiled extensions are available for Linux, macOS, and Windows.
## \[2.28.2] - 2026-03-08
[Section titled “\[2.28.2\] - 2026-03-08”](#2282---2026-03-08)
### Fixed
[Section titled “Fixed”](#fixed-8)
* **Publish workflow republish flag**: Fixed republish mode skipping all publish jobs because `INPUT_REF` resolved to a branch name instead of the tag ref.
* **Definition list fixture**: Aligned real-world test fixture for `<dl>`/`<dt>`/`<dd>` with actual converter output (plain text, no Pandoc-style `:` prefix).
## \[2.28.1] - 2026-03-06
[Section titled “\[2.28.1\] - 2026-03-06”](#2281---2026-03-06)
### Fixed
[Section titled “Fixed”](#fixed-9)
* **Panic with multi-byte UTF-8 and visitor** ([#218](https://github.com/xberg-io/html-to-markdown/issues/218)): Fixed a panic (“byte index N is not a char boundary”) when converting HTML containing multi-byte UTF-8 characters (Cyrillic, CJK, emoji, etc.) with tabs between block elements and any visitor. The stale byte position captured before whitespace trimming could land inside a multi-byte character when new content was appended.
* **Java formatting**: Fixed spotless formatting violations in `HtmlToMarkdown.java`, `TableData.java`, and `TableExtractionResult.java`.
## \[2.28.0] - 2026-03-05
[Section titled “\[2.28.0\] - 2026-03-05”](#2280---2026-03-05)
### Added
[Section titled “Added”](#added-3)
* **Table extraction API**: New `convert_with_tables` function that extracts structured table data during HTML to Markdown conversion. Returns `TableData` structs containing cell contents as `Vec<Vec<String>>`, rendered markdown output, and per-row header flags. Uses the visitor pattern internally with a built-in `TableCollector` to capture table structure in a single pass. Available across all language bindings:
* **Rust**: `convert_with_tables(html, options, metadata_config)` returning `ConversionWithTables`
* **Python**: `convert_with_tables(html, options, preprocessing, metadata_config)` returning `TableExtractionResult`
* **TypeScript/Node.js**: `convertWithTables(html, options?, metadataConfig?)` returning `TableExtraction`
* **Ruby**: `HtmlToMarkdown.convert_with_tables(html, options, metadata_config)` returning a Hash
* **PHP**: `HtmlToMarkdown::convertWithTables($html, $options, $metadataConfig)` returning `TableExtractionResult`
* **Go**: `ConvertWithTables(html)` returning `TableExtractionResult`
* **Java**: `HtmlToMarkdown.convertWithTables(html)` returning `TableExtractionResult`
* **C#**: `HtmlToMarkdownConverter.ConvertWithTables(html)` returning `TableExtractionResult`
* **Elixir**: `HtmlToMarkdown.convert_with_tables(html, options, metadata_config)` returning `{:ok, content, tables, metadata}`
* **R**: `convert_with_tables(html, options, metadata_config)` returning a list
* **C (FFI)**: `html_to_markdown_convert_with_tables(html, options_json, metadata_json)` returning JSON
* **WASM**: `convertWithTables(html, options?, metadataConfig?)` returning a JS object
### Fixed
[Section titled “Fixed”](#fixed-10)
* **Plain text fast path skipping visitor callbacks**: When `OutputFormat::Plain` was used with `convert_with_tables`, the plain text fast path returned before the visitor could extract table data, resulting in empty tables. The conversion pipeline now runs the full visitor walk before returning plain text content.
## \[2.27.3] - 2026-03-05
[Section titled “\[2.27.3\] - 2026-03-05”](#2273---2026-03-05)
### Fixed
[Section titled “Fixed”](#fixed-11)
* **Panic on block_content_start out of bounds**: Fixed a crash (`byte index N is out of bounds`) in text node processing when inline handlers (e.g. `<strong>`, `<em>`) collected children into a fresh buffer while inheriting a parent paragraph context. The `block_content_start` index pointed into the wrong buffer, causing a panic on certain HTML structures — notably `<details>` containing `<p>` with inline formatting. (Issues #216, #217)
## \[2.27.2] - 2026-03-02
[Section titled “\[2.27.2\] - 2026-03-02”](#2272---2026-03-02)
### Fixed
[Section titled “Fixed”](#fixed-12)
* **Plain text list items missing markers**: `<ul>` and `<ol>` list items in `OutputFormat::Plain` were output without any bullet or number prefix. Now emits `-` for unordered lists and sequential `N.` for ordered lists, respecting the `start` attribute on `<ol>`.
## \[2.27.1] - 2026-03-01
[Section titled “\[2.27.1\] - 2026-03-01”](#2271---2026-03-01)
### Fixed
[Section titled “Fixed”](#fixed-13)
* **Colon introduced into definition list text**: `<dd>` elements inside `<dl>` were incorrectly prefixed with `:` (Pandoc definition list syntax), introducing spurious colons into converted text. Standard Markdown and GFM do not support definition list syntax, so `<dd>` content is now output as plain blocks. (Issue #214, thanks @smoyerx)
* **Go test app go.sum out of sync**: Updated `tests/test_apps/go/go.sum` to match the v2.27.0 module version, fixing the CI Go lint job.
## \[2.27.0] - 2026-03-01
[Section titled “\[2.27.0\] - 2026-03-01”](#2270---2026-03-01)
### Added
[Section titled “Added”](#added-4)
* **Plain text output format**: New `OutputFormat::Plain` option that strips all markup and returns only visible text content. Set `output_format` to `"plain"` (also accepts `"plaintext"` or `"text"`). This fast-path bypasses the full Markdown/Djot conversion pipeline — after DOM parsing, a lightweight text extractor walks the tree collecting only visible text with structural whitespace. Useful for search indexing, text extraction, and feeding content to LLMs.
## \[2.26.3] - 2026-02-28
[Section titled “\[2.26.3\] - 2026-02-28”](#2263---2026-02-28)
### Fixed
[Section titled “Fixed”](#fixed-14)
* **Subscript/superscript content silently dropped**: When `sub_symbol` or `sup_symbol` was empty (the default), text inside `<sub>` and `<sup>` tags was discarded entirely — e.g. `H<sub>2</sub>O` produced `HO` instead of `H2O`.
* **Missing whitespace between newline-separated inline elements**: Whitespace-only text nodes containing newlines between adjacent inline elements (e.g. `<a>…</a>\n<a>…</a>`) were dropped, causing links and other inline markup to merge without a word boundary. Now collapses to a single space per HTML white-space normalization rules.
## \[2.26.2] - 2026-02-28
[Section titled “\[2.26.2\] - 2026-02-28”](#2262---2026-02-28)
### Fixed
[Section titled “Fixed”](#fixed-15)
* **Inconsistent whitespace before inline elements across paragraphs**: Fixed a stateful bug where `\n` before `<a>`, `<strong>`, `<em>`, and other inline elements inside `<p>` tags was handled differently depending on the paragraph’s position in the document. The second and subsequent paragraphs would drop the space before inline elements, producing `text[link](url)` instead of `text [link](url)`. (Issue #212, thanks @haroldparis)
## \[2.26.1] - 2026-02-27
[Section titled “\[2.26.1\] - 2026-02-27”](#2261---2026-02-27)
### Fixed
[Section titled “Fixed”](#fixed-16)
* **YAML frontmatter in `convert_with_metadata` output**: `convert_with_metadata` no longer prepends YAML frontmatter to the markdown string. Since metadata is returned as a structured `ExtendedMetadata` object, embedding it in the content string was redundant and polluted the output.
## \[2.26.0] - 2026-02-26
[Section titled “\[2.26.0\] - 2026-02-26”](#2260---2026-02-26)
### Added
[Section titled “Added”](#added-5)
* **C FFI distribution infrastructure**: Distribution-grade C FFI library with CMake/pkg-config integration, installation scripts, and packaging for system-level consumption.
* **C FFI test coverage**: Comprehensive C test suite covering conversion, metadata extraction, error handling, visitor pattern, profiling, and version queries.
* **C documentation and examples**: C API reference, getting-started snippets, and example programs for basic conversion, metadata extraction, and visitor pattern usage.
### Fixed
[Section titled “Fixed”](#fixed-17)
* **R package r-universe build**: Configure scripts now download the source archive from GitHub when the monorepo is unavailable, enabling r-universe and standalone source installs to vendor crates automatically.
## \[2.25.2] - 2026-02-25
[Section titled “\[2.25.2\] - 2026-02-25”](#2252---2026-02-25)
### Fixed
[Section titled “Fixed”](#fixed-18)
* **Visitor panic with metadata extraction**: Fixed an out-of-bounds slice panic when using visitors (e.g. image visitors returning `Custom`) combined with metadata extraction on minified HTML. The issue occurred because parent element output offsets became stale after child visitor truncations. (PR #204, thanks @gmalette)
### Added
[Section titled “Added”](#added-6)
* **R language bindings**: Full-parity R bindings via extendr framework with support for `convert()`, `convert_with_options()`, `convert_with_options_handle()`, `convert_with_metadata()`, `convert_with_inline_images()`, `convert_with_visitor()`, and profiling. Includes `conversion_options()` helper, testthat test suite, CI workflow, lintr/styler pre-commit hooks, and task automation.
* **R CRAN publishing infrastructure**: Added `publish-cran` job to publish workflow, `cran-comments.md`, and `NEWS.md` for CRAN submission compliance.
### Changed
[Section titled “Changed”](#changed-3)
* **Workspace restructuring**: Moved Ruby native crate out of the root Cargo workspace into a standalone workspace (matching Elixir/R pattern), resolving `clang-sys` link conflict with `ext-php-rs` 0.15.6.
* **Rust update task**: Now updates dependencies in all separate workspaces (Ruby, Elixir, R) via `--manifest-path` entries.
* **Upgraded `wasmtime`** from 41 to 42.
* **Upgraded `ext-php-rs`** from 0.15.4 to 0.15.6.
* **Upgraded `pyo3`** from 0.28.1 to 0.28.2.
* **Upgraded `wasm-bindgen`** from 0.2.112 to 0.2.113.
* **Upgraded `rustls`** from 0.23.36 to 0.23.37.
## \[2.25.1] - 2026-02-17
[Section titled “\[2.25.1\] - 2026-02-17”](#2251---2026-02-17)
### Fixed
[Section titled “Fixed”](#fixed-19)
* **hOCR heading detection**: Improved hierarchy logic to use font size (`x_fsize`) and bbox height as a proxy when detecting headings. Large-font paragraphs now support longer text (up to 80 chars) and single-word headings. Added comprehensive test coverage for heading detection edge cases.
## \[2.25.0] - 2026-02-15
[Section titled “\[2.25.0\] - 2026-02-15”](#2250---2026-02-15)
### Added
[Section titled “Added”](#added-7)
* **Bun runtime support**: Official support for Bun 1.2+ via Node-API compatibility. The existing NAPI-RS bindings work in Bun without changes. Added Bun to CI test matrix and updated documentation to reflect runtime compatibility.
### Changed
[Section titled “Changed”](#changed-4)
* **Vendored `markup5ever_rcdom`**: Brought the `markup5ever_rcdom` code (MIT/Apache-2.0) into the core crate as an internal `rcdom` module. This removes the external dependency on the “+unofficial” crate, eliminates the unused `xml5ever` transitive dependency, and removes the pinned `html5ever`/`markup5ever_rcdom` version constraints. See `ATTRIBUTIONS.md` for license details.
* **Upgraded `html5ever`** from 0.36.1 to 0.38.0 (now unpinned).
* **Upgraded `pyo3`** from 0.28.0 to 0.28.1.
## \[2.24.6] - 2026-02-14
[Section titled “\[2.24.6\] - 2026-02-14”](#2246---2026-02-14)
### Fixed
[Section titled “Fixed”](#fixed-20)
* **Dependency update stability**: Pinned compatible `html5ever`/`markup5ever_rcdom` versions to prevent trait-mismatch breakages during workspace dependency updates.
* **Python bindings build**: Added explicit `#[pyclass(from_py_object)]` on Python config wrapper classes to avoid PyO3 deprecation failures under `-D warnings`.
* **Rust lint consistency**: Aligned crate-level clippy configuration so `multiple_crate_versions` does not fail Node/WASM/FFI crate lint runs.
* **WASM dependency behavior**: Updated hashing dependency configuration to avoid wasm randomness backend breakage after dependency updates.
* **PHP PIE publish verification (macOS)**: Hardened PIE verification/build scripts for Darwin linker behavior and shell-safe package spec handling.
* **CI reliability**: Updated validation and Python CI tasks to reduce flakiness (PHP 8.4 setup in validate; avoid redundant Rust CLI release builds in Python test runs).
## \[2.24.5] - 2026-02-01
[Section titled “\[2.24.5\] - 2026-02-01”](#2245---2026-02-01)
### Fixed
[Section titled “Fixed”](#fixed-21)
* **Subscript/superscript whitespace handling**: Subscript and superscript tags now trim inner whitespace and place it outside delimiters, matching the behavior of bold, italic, and strikethrough (issue #202).
## \[2.24.4] - 2026-01-31
[Section titled “\[2.24.4\] - 2026-01-31”](#2244---2026-01-31)
### Performance
[Section titled “Performance”](#performance)
* **Reduced allocations in hot conversion paths**: Return `Cow<str>` from escape to avoid allocating on no-op paths, replace `.repeat()` with direct push loops in heading/list/table/div/paragraph formatters, eliminate `collect::<Vec>::join()` in text dedentation, and use `AHashMap` for hOCR property maps.
### Fixed
[Section titled “Fixed”](#fixed-22)
* **WASM builds**: Updated `getrandom` backend configuration from `"js"` to `"wasm_js"` for compatibility with getrandom 0.3.x.
* **Elixir/Ruby vendor scripts**: Added missing `ahash` workspace dependency replacement for standalone builds.
## \[2.24.3] - 2026-01-31
[Section titled “\[2.24.3\] - 2026-01-31”](#2243---2026-01-31)
### Fixed
[Section titled “Fixed”](#fixed-23)
* **Definition lists**: Ensure `<dl>/<dt>/<dd>` output is consistent regardless of HTML whitespace/minification, and properly indent multiline definition content (issue #200).
* **Link labels**: Removed hard truncation of long link labels to avoid broken Markdown for large image links (issue #199).
## \[2.24.2] - 2026-01-29
[Section titled “\[2.24.2\] - 2026-01-29”](#2242---2026-01-29)
### Fixed
[Section titled “Fixed”](#fixed-24)
* **Java packaging**: Bundle native FFI libraries in published Maven JAR for all platforms (linux-x86_64, linux-aarch64, osx-aarch64, windows-x86_64). The Java package now works out-of-the-box when installed from Maven Central without requiring local FFI builds or manual java.library.path configuration. Native libraries are automatically extracted to a temp directory on first use with platform detection and fallback support.
## \[2.24.1] - 2026-01-27
[Section titled “\[2.24.1\] - 2026-01-27”](#2241---2026-01-27)
### Fixed
[Section titled “Fixed”](#fixed-25)
* **UTF-16 recovery**: Automatically recovers UTF-16 HTML (including data without BOM) that was read via lossy UTF-8 decoding, instead of rejecting it as binary data.
* **URL sanitization**: Hardened markdown-like URL sanitization to extract the real URL from `...[text](url)` patterns in `href`/`src` attributes, preventing caller-side URL join/parsing errors.
* **Issue #190 coverage**: Added regression fixtures and tests covering the reported real-world HTML inputs.
## \[2.24.0] - 2026-01-24
[Section titled “\[2.24.0\] - 2026-01-24”](#2240---2026-01-24)
### Changed
[Section titled “Changed”](#changed-5)
* **Bindings API**: Removed `_json` conversion entrypoints across bindings; convert functions now pass full option payloads directly.
### Fixed
[Section titled “Fixed”](#fixed-26)
* **Visitor docs**: Corrected Python visitor documentation and examples (argument order + ctx access).
* **Python visitor options**: `convert_with_visitor` now respects full conversion options payloads.
* **skip_images**: Skip flag now suppresses SVG/graphic outputs in addition to `<img>`.
* **Code block dedent**: Handles Unicode whitespace without panicking on UTF-8 boundaries.
* **Input validation**: Tolerates small NUL byte artifacts and strips them before conversion.
## \[2.23.6] - 2026-01-21
[Section titled “\[2.23.6\] - 2026-01-21”](#2236---2026-01-21)
### Fixed
[Section titled “Fixed”](#fixed-27)
* **pnpm lockfile synchronization**: Fixed pnpm lockfile to include Node.js platform-specific optional dependency version updates (2.19.0-rc.1 → 2.23.6) that were applied during v2.23.5 version sync. This resolves the `ERR_PNPM_OUTDATED_LOCKFILE` errors that caused the v2.23.5 publish workflow to fail.
* **CI Java version**: Updated CI Java workflow from Java 24 to Java 25 to match maven.compiler.release=25 configuration, ensuring CI and local builds use the same compiler version.
## \[2.23.5] - 2026-01-21
[Section titled “\[2.23.5\] - 2026-01-21”](#2235---2026-01-21)
### Fixed
[Section titled “Fixed”](#fixed-28)
* **Maven Central publishing**: Corrected group ID in Maven Central check script from legacy `io.github.goldziher` to `dev.kreuzberg`, enabling successful Java package publishing. This resolves the issue where Java v2.23.4 failed to publish to Maven Central.
* **Go module publishing**: Added automated Go module tag creation (`packages/go/v{version}`) to publish workflow, ensuring Go packages are immediately available on Go proxy after release.
* **Go FFI version synchronization**: Updated Go FFI default version constants from outdated versions (2.19.1/2.23.0) to 2.23.5 in both `ffi_loader.go` and `cmd/install/main.go`, ensuring automatic downloads use the correct library version.
* **Node.js platform dependencies**: Synchronized all platform-specific optional dependencies in `@kreuzberg/html-to-markdown-node` package.json from 2.19.0-rc.1 to match main package version, preventing dependency resolution issues.
* **Java benchmark packaging**: Updated benchmark-pom.xml to use correct group ID (`dev.kreuzberg`), version (2.23.5), and main class namespace (`dev.kreuzberg.benchmark.Benchmark`). Removed outdated generated `dependency-reduced-pom.xml`.
* **PHP package references**: Updated all PHP package references from `goldziher/html-to-markdown` to `xberg-io/html-to-markdown` across composer.json, PIE verification scripts, and smoke test actions to reflect current package organization.
* **Java smoke tests**: Updated smoke-java GitHub action to use correct group ID (`dev.kreuzberg`) and package namespace (`dev.kreuzberg.htmltomarkdown.SmokeTest`) for JAR installation and test execution.
* **Build tooling**: Fixed Python script execution in task runner to use `uv run python3` instead of system python3, ensuring consistent dependency resolution. Added PyYAML and Jinja2 to workspace dev dependencies.
* **Version sync automation**: Enhanced version sync script to automatically update Node.js platform-specific optional dependencies alongside main package version, preventing manual version drift.
## \[2.23.4] - 2026-01-20
[Section titled “\[2.23.4\] - 2026-01-20”](#2234---2026-01-20)
### Fixed
[Section titled “Fixed”](#fixed-29)
* **TypeScript wrapper publishing**: Fixed TypeScript wrapper dependency resolution by installing dependencies directly from npm registry instead of from workspace after Node packages are published. This ensures `@kreuzberg/html-to-markdown-node` is available from npm when building the TypeScript wrapper, eliminating the workspace resolution issues that caused previous build failures.
## \[2.23.3] - 2026-01-20
[Section titled “\[2.23.3\] - 2026-01-20”](#2233---2026-01-20)
### Fixed
[Section titled “Fixed”](#fixed-30)
* **Go FFI packaging**: Fixed missing `html_to_markdown.h` header file in Go FFI archive tarballs, which caused `go:generate` installation to fail with “fatal error: ‘html_to_markdown.h’ file not found”. The header is now included in all platform archives (tar.gz and zip).
* **TypeScript wrapper publishing**: Fixed pnpm lockfile frozen mode error during TypeScript wrapper dependency reinstallation by adding `--no-frozen-lockfile` flag. The reinstall step after publishing Node packages now correctly updates workspace dependencies despite lockfile version mismatches.
## \[2.23.2] - 2026-01-20
[Section titled “\[2.23.2\] - 2026-01-20”](#2232---2026-01-20)
### Fixed
[Section titled “Fixed”](#fixed-31)
* **TypeScript wrapper publishing**: Fixed TypeScript wrapper build failures by moving the build and publish steps into the same `publish-node` job. This eliminates npm CDN propagation delays that caused `@kreuzberg/html-to-markdown` to fail building because `@kreuzberg/html-to-markdown-node` wasn’t available yet. Added workspace dependency reinstallation step to ensure pnpm correctly resolves the local package after publishing.
* **Go FFI library installation**: Fixed critical bugs in the `go:generate` install script that prevented automatic FFI library downloads:
* Corrected artifact naming from `go-ffi-{platform}.tar.gz` to `html-to-markdown-ffi-{version}-{platform}.tar.gz`
* Fixed platform mapping to match GitHub release artifacts (darwin-arm64, linux-x64, etc.)
* Added support for all library formats (.dylib for macOS, .so for Linux, .dll for Windows)
* **Ruby native Cargo.toml**: Fixed workspace dependency configuration to use `workspace = true` instead of vendored path reference, preventing Cargo workspace resolution failures during builds.
* **CI workflows**: Upgraded all CI workflows from Java 24 to Java 25 to match maven.compiler.release=25 configuration in pom.xml.
* **Go linting**: Resolved golangci-lint warnings by adding constants for OS names and library names, and converting if-else chains to switch statements.
### Changed
[Section titled “Changed”](#changed-6)
* **Go README**: Updated installation documentation to explain the `go:generate` workflow for automatic FFI library installation, including details about caching in `~/.html-to-markdown/` and alternative manual configuration.
## \[2.23.1] - 2026-01-19
[Section titled “\[2.23.1\] - 2026-01-19”](#2231---2026-01-19)
### Fixed
[Section titled “Fixed”](#fixed-32)
* **Go module versioning**: Created 14 missing Go module tags (packages/go/v2.16.1, v2.19.1-v2.19.8, v2.20.1, v2.21.1, v2.22.1-v2.22.5) to ensure all versions since v2.15.0 are available via Go proxy. Users can now `go get` any version from v2.15.0 onwards.
* **TypeScript wrapper publishing**: Added missing `publish-typescript` job to publish workflow to properly publish `@kreuzberg/html-to-markdown` TypeScript wrapper package to npm alongside the native Node.js bindings (`@kreuzberg/html-to-markdown-node`).
* **Ruby gem vendoring**: Fixed Ruby gem installation failures due to missing `.cargo-checksum.json` files. Updated gemspec to include hidden files with `File::FNM_DOTMATCH` flag, and improved vendoring script to generate checksums correctly with `--locked` flag and proper cleanup.
* **Elixir package size**: Reduced Hex package size from 134 MB to under 128 MB limit by aggressively removing unnecessary files from vendored dependencies (tests, docs, examples, static libraries, Windows-only crates on Unix builds).
### Added
[Section titled “Added”](#added-8)
* **Go automatic FFI library installation**: Implemented `go:generate` pattern following Kreuzberg approach. Added `cmd/install` package that automatically downloads platform-specific FFI libraries from GitHub releases and generates CGO flags. Users can now run `go generate` after installation instead of manually setting `CGO_CFLAGS` and `CGO_LDFLAGS` environment variables. FFI loader updated to check `~/.html-to-markdown/` for installed libraries.
## \[2.23.0] - 2026-01-18
[Section titled “\[2.23.0\] - 2026-01-18”](#2230---2026-01-18)
### Added
[Section titled “Added”](#added-9)
* **Djot output format support**: New `output_format` option in `ConversionOptions` enables conversion to [Djot](https://djot.net/) lightweight markup language as an alternative to Markdown. Djot uses different syntax for emphasis (`_text_`), strong (`*text*`), strikethrough (`{-text-}`), inserted (`{+text+}`), highlighted (`{=text=}`), subscript (`~text~`), and superscript (`^text^`).
* **CLI**: Added `--output-format` / `-f` flag to specify output format (`markdown` or `djot`)
* **All language bindings**: OutputFormat enum/option added to Python, TypeScript/Node.js, Ruby, PHP, Elixir, Go, Java, and C# bindings
* **Documentation**: Added Djot output format section to all package READMEs with syntax comparison table
### Fixed
[Section titled “Fixed”](#fixed-33)
* **Python**: Fixed async visitor bridge to properly await coroutines. `PyAsyncVisitorBridge::call_visitor_method_sync()` now detects async methods via `__await__` attribute and uses `PYTHON_TASK_LOCALS` event loop for proper async execution (issue #187)
* **Ruby**: Fixed visitor parameter being ignored in `convert()` wrapper method. Now correctly passes visitor to native `convert_with_visitor` function when provided (issue #187)
### Changed
[Section titled “Changed”](#changed-7)
* **Rust**: Updated `async-visitor` feature to include required `tokio` “sync” feature for `Mutex` support
* **Documentation**: Added comprehensive visitor pattern support matrix showing which bindings support visitors
* **Documentation**: Documented WASM visitor pattern architectural limitation with four alternative approaches
## \[2.22.6] - 2026-01-16
[Section titled “\[2.22.6\] - 2026-01-16”](#2226---2026-01-16)
### Fixed
[Section titled “Fixed”](#fixed-34)
* **Ruby gem dependency resolution**: Ruby native extension now uses workspace version inheritance with vendoring approach. During gem build, the entire `html-to-markdown` crate is vendored with exact dependency versions into `packages/ruby/vendor/`, making gems completely self-contained and eliminating crates.io dependency resolution during installation. Local development uses symlink to workspace crate for seamless workflow.
* **URL parsing robustness**: Fixed IPv6 URL parsing error when processing malformed markdown-like URLs in HTML attributes (e.g., `//[domain.com/path](http://domain.com/path)`). New `sanitize_markdown_url()` function detects and extracts actual URLs from markdown syntax that wasn’t properly converted in source HTML. Applied to both link `href` and image `src` attributes (fixes issue #186).
### Changed
[Section titled “Changed”](#changed-8)
* **Ruby gem build process**: Added `vendor-html-to-markdown.sh` script that creates standalone vendor workspace before gem packaging. Ruby native `Cargo.toml` now references vendored path for maximum reproducibility and build reliability.
## \[2.22.5] - 2026-01-16
[Section titled “\[2.22.5\] - 2026-01-16”](#2225---2026-01-16)
### Fixed
[Section titled “Fixed”](#fixed-35)
* **Core**: Added `#[serde(default)]` attribute to `ConversionOptions` struct to enable partial JSON deserialization. This allows deserializing JSON with only a subset of fields specified, using default values for missing fields. Fixes compatibility with language bindings (C#, Go, Java) that serialize partial configuration objects.
## \[2.22.4] - 2026-01-15
[Section titled “\[2.22.4\] - 2026-01-15”](#2224---2026-01-15)
### Fixed
[Section titled “Fixed”](#fixed-36)
* **Core**: Fixed `br_in_tables` option not being respected correctly. HTML `<br>` tags in table cells now properly convert to markdown line breaks (spaces or backslash style based on `newline_style` option), while block elements (divs, paragraphs) continue to generate literal `<br>` tags when needed for rowspan scenarios (issue #184)
* **WASM**: Updated GitHub Pages demo to v2.22.4 with latest BR tag handling fixes
## \[2.22.3] - 2026-01-14
[Section titled “\[2.22.3\] - 2026-01-14”](#2223---2026-01-14)
### Fixed
[Section titled “Fixed”](#fixed-37)
* **Python**: Exposed `skip_images` option in `ConversionOptions` API, including type stub files (.pyi) for proper type checking support (issue #183)
* **Elixir**: Added `skip_images` option to `HtmlToMarkdown.Options` module (was completely missing from Elixir binding)
* **Core**: Fixed `<br>` tags being output literally in table cells instead of converting to proper Markdown line breaks. Table cell paragraph and div separators now respect `newline_style` option (issue #184)
## \[2.22.2] - 2026-01-13
[Section titled “\[2.22.2\] - 2026-01-13”](#2222---2026-01-13)
### Fixed
[Section titled “Fixed”](#fixed-38)
* **Ruby gem standalone build** - Fixed Ruby gem failing to build when installed from RubyGems. Removed `lints.workspace = true` (which requires workspace context) and added inline lint configuration. This resolves issue #181.
* **Ruby gem version pinning** - Changed `html-to-markdown-rs` dependency from loose semver (`"2.x.x"`) to exact pin (`"=2.22.2"`) to prevent older gems from pulling incompatible newer crate versions.
* **Version sync script** - Updated `sync_versions.py` to preserve exact version pin prefix (`=`) when syncing Ruby gem dependencies.
## \[2.22.1] - 2026-01-13
[Section titled “\[2.22.1\] - 2026-01-13”](#2221---2026-01-13)
### Fixed
[Section titled “Fixed”](#fixed-39)
* **Java Maven Central publishing** - Fixed Maven Central deployment by adding proper `publish` profile with `central-publishing-maven-plugin` configuration. The plugin is now correctly activated with `-Ppublish` flag and uses `ossrh` server credentials.
* **Java Spotless formatting** - Updated google-java-format to 1.28.0 for Java 25 compatibility.
## \[2.22.0] - 2026-01-13
[Section titled “\[2.22.0\] - 2026-01-13”](#2220---2026-01-13)
### Fixed
[Section titled “Fixed”](#fixed-40)
* **C FFI visitor implementation** - Fixed `html_to_markdown_convert_with_visitor` to properly use the visitor handle during conversion instead of discarding it. Previously the visitor was created but the plain `convert()` function was called instead of `convert_with_visitor()`.
* **C# visitor callbacks** - P/Invoke bindings now correctly invoke visitor callbacks during HTML to Markdown conversion (42/42 tests passing).
* **Go visitor callbacks** - Removed regex-based post-processing workaround; Go bindings now use real FFI visitor callbacks with proper struct field ordering.
* **PHP visitor callbacks** - Wired up `PhpVisitorBridge` to pass visitor to Rust core instead of ignoring the visitor parameter.
* **Java visitor callbacks** - Added Panama FFI upcall stubs for all 38 visitor callbacks, enabling full visitor pattern support (95/95 tests passing).
### Added
[Section titled “Added”](#added-10)
* **Java `VisitorCallbackFactory`** - New class that creates Panama FFI upcall stubs for visitor callbacks, enabling Java code to receive callbacks from the Rust core during conversion.
* **Java `HtmlToMarkdown.convertWithVisitor()`** - Public API method for converting HTML with a custom visitor implementation.
## \[2.21.1] - 2026-01-13
[Section titled “\[2.21.1\] - 2026-01-13”](#2211---2026-01-13)
### Added
[Section titled “Added”](#added-11)
* **Serde serialization support for ConversionOptions** - Added `Serialize` and `Deserialize` traits to `ConversionOptions`, `PreprocessingOptions`, and all related structs. Enables JSON serialization/deserialization with camelCase field naming and lowercase string enum representations.
### Changed
[Section titled “Changed”](#changed-9)
* **Major refactor: Complete Phase 1 modular architecture** - Restructured core converter into modular handler components:
* Extracted block element handlers (block-level HTML elements)
* Extracted inline element handlers (2,363 lines of focused code)
* Extracted table, list, and media handlers (2,528 lines)
* Extracted semantic and form handlers (1,532 lines)
* Improved code organization and maintainability across all language bindings
* **Unified FFI bindings architecture** - Consolidated common binding logic into shared crate, reducing duplication across Python, TypeScript, Ruby, PHP, Go, and Java bindings
* **Added visitor callback code generation system** - FFI now supports dynamic visitor callbacks for all language bindings (Python, Ruby, PHP, Elixir, etc.)
* **Enhanced preprocessing system** - Footer and nav element removal now integrated into preprocessing pipeline
* **Improved custom element detection** - Enhanced `has_custom_element_tags` to accurately detect only tag names with hyphens
### Internal
[Section titled “Internal”](#internal)
* Updated dependencies across all language bindings (Python, Ruby, PHP, JavaScript, Go, etc.)
* Refactored benchmark harness to modularize script adapters and reduce code duplication
* Refactored performance examples to extract and reuse shared utilities
* Improved sync_versions.py to handle all internal workspace dependency version pins
* Refactored README generation script to modularize template handling
* Improved clippy lint handling and CI coverage workflows
* Added documentation to Node.js binding example files
## \[2.21.0] - 2026-01-10
[Section titled “\[2.21.0\] - 2026-01-10”](#2210---2026-01-10)
### Added
[Section titled “Added”](#added-12)
* **`skip_images` configuration option** - New option to skip all `<img>` elements during conversion, enabling greater control over image handling in the output.
* **Optional visitor parameter across all convert functions** - Unified API for applying visitor patterns to all conversion modes:
* `convert(html, options, visitor)` - Basic conversion with optional visitor
* `convert_with_inline_images(html, options, image_cfg, visitor)` - Inline image extraction with optional visitor
* `convert_with_metadata(html, options, metadata_cfg, visitor)` - Metadata extraction with optional visitor
* **Visitor pattern integration with advanced features** - Support for using visitor pattern simultaneously with inline images and metadata extraction, providing complete control over the conversion process.
* **Comprehensive test coverage** - Added tests validating `skip_images` functionality and visitor pattern integration across all conversion functions and language bindings.
### Changed
[Section titled “Changed”](#changed-10)
* **Visitor parameter unified across all APIs** - The visitor parameter is now optional on all conversion functions, enabling consistent API design across basic, inline-images, and metadata extraction paths.
* **Improved feature-gated architecture** - Refined the feature gate handling for better flexibility when combining visitor patterns with other optional features.
### Deprecated
[Section titled “Deprecated”](#deprecated-1)
* **`convert_with_visitor()` function** - Deprecated in favor of passing visitor as an optional parameter to `convert()`. The dedicated function will be removed in a future major release. Use `convert(html, options, visitor)` instead.
### Fixed
[Section titled “Fixed”](#fixed-41)
* **Unused dependency warnings in npm packages** - Resolved unused dependency warnings reported during builds of JavaScript/TypeScript packages.
* **Feature gate handling for visitor combinations** - Fixed issues with feature gate combinations when using visitor patterns alongside inline images and metadata extraction.
## \[2.20.1] - 2026-01-09
[Section titled “\[2.20.1\] - 2026-01-09”](#2201---2026-01-09)
### Code Quality
[Section titled “Code Quality”](#code-quality)
* **Resolved all clippy warnings comprehensively**: Fixed 207+ clippy pedantic/nursery warnings across entire workspace
* Removed blanket `#![allow(clippy::pedantic)]` directives from all crate roots
* Fixed trivial copy pass-by-ref issues in converter functions
* Added missing documentation sections (# Errors) to public APIs
* Fixed doc markdown formatting (added backticks to technical terms)
* Applied selective allows only for architecturally justified cases
* FFI/binding layers use targeted allows due to interop constraints
* Core library maintains strict clippy compliance
* **Updated workspace lint configuration**: Changed pedantic lints from deny to warn to allow module-level selective overrides
* **Dependency modernization**: Migrated from `once_cell::sync::Lazy` to stdlib `std::sync::LazyLock` (stabilized in Rust 1.80+)
## \[2.20.0] - 2026-01-05
[Section titled “\[2.20.0\] - 2026-01-05”](#2200---2026-01-05)
### Dependencies
[Section titled “Dependencies”](#dependencies)
* **Updated reqwest to 0.13.1**: Migrated to new rustls defaults
* rustls is now the default TLS backend (previously native-tls)
* aws-lc is the default crypto provider (previously ring)
* rustls-platform-verifier is used by default for root certificates
* All reqwest features updated to new naming conventions
* **Updated development dependencies**: Updated pnpm packages, Ruby gems, and pre-commit hooks
* oxlint pre-commit hook updated from v1.36.0 to v1.37.0
* All language bindings dependencies refreshed
### Infrastructure
[Section titled “Infrastructure”](#infrastructure)
* **Fixed C# package update task**: Updated dotnet list command to specify project files explicitly
* Prevents “project or solution file could not be found” errors
* Now checks both HtmlToMarkdown.csproj and HtmlToMarkdown.Tests.csproj individually
## \[2.19.8] - 2026-01-05
[Section titled “\[2.19.8\] - 2026-01-05”](#2198---2026-01-05)
### Bug Fixes
[Section titled “Bug Fixes”](#bug-fixes)
* **Blockquote newline preservation**: Fixed Issue #176 - Newlines were not preserved when block elements like `<strong>` were directly adjacent to `<blockquote>` elements
* Blockquotes now add proper spacing before and after themselves
* Fixed blockquote+paragraph spacing to match CommonMark spec
* Fixed blockquote+HR spacing to avoid extra newlines
* Added comprehensive regression tests to prevent future regressions
* Maintains CommonMark compliance (132/132 tests passing)
### Improvements
[Section titled “Improvements”](#improvements)
* **Debug logging cleanup**: Removed extensive debug logging from hOCR processing and core converter
* Removed \~30 debug eprintln! statements that were spamming output
* Removed unused debug parameters from hOCR functions (parse_properties, reconstruct_table, extract_hocr_document, etc.)
* Cleaner output and reduced noise during HTML to Markdown conversion
## \[2.19.7] - 2026-01-03
[Section titled “\[2.19.7\] - 2026-01-03”](#2197---2026-01-03)
### Improvements
[Section titled “Improvements”](#improvements-1)
* **Homebrew bottle CI debugging**: Added verification steps to diagnose artifact upload/download issues
* Added verification after bottle creation to confirm file exists in workspace
* Added `if-no-files-found: error` to fail fast if bottle file not found during upload
* Added verification after artifact download to show what was actually retrieved
* These steps will help identify why Homebrew bottle artifacts aren’t being found in release workflow
## \[2.19.6] - 2026-01-03
[Section titled “\[2.19.6\] - 2026-01-03”](#2196---2026-01-03)
### Bug Fixes
[Section titled “Bug Fixes”](#bug-fixes-1)
* **WASM npm package publishing**: Fixed Issue #172 - WASM package was published with only 3 files (LICENSE, package.json, README.md) instead of 25 files
* Root cause: publish workflow downloaded WASM artifact tarballs but never extracted them before running `npm publish`
* Added extraction step in `.github/workflows/publish.yaml` to unpack dist/, dist-node/, and dist-web/ directories
* Added safeguard to remove .gitignore files from dist directories that could exclude content
* Complete package now includes all WASM binaries and JavaScript wrappers (7.8 MB unpacked)
## \[2.19.5] - 2025-01-02
[Section titled “\[2.19.5\] - 2025-01-02”](#2195---2025-01-02)
### Bug Fixes
[Section titled “Bug Fixes”](#bug-fixes-2)
* **Homebrew bottle naming**: Fixed bottle filename format to match Homebrew convention
* Changed from double-dash (`html-to-markdown--2.19.x`) to single-dash (`html-to-markdown-2.19.x`)
* Homebrew constructs bottle URLs based on formula name and version, expecting single dash separator
* Fixes bottle download failures when installing via `brew install`
## \[2.19.4] - 2025-01-02
[Section titled “\[2.19.4\] - 2025-01-02”](#2194---2025-01-02)
### Bug Fixes
[Section titled “Bug Fixes”](#bug-fixes-3)
* **Homebrew formula publishing**: Fixed publish workflow script that updates the Homebrew tap formula
* Corrected bottle block deletion regex (was looking for `# bottle do` instead of `bottle do`), preventing duplicate bottle blocks from accumulating on each release
* Added automatic source tarball SHA256 computation and formula update to ensure correct checksums
* Formula now properly replaces old bottle blocks with new ones rather than appending
## \[2.19.3] - 2025-01-02
[Section titled “\[2.19.3\] - 2025-01-02”](#2193---2025-01-02)
### Bug Fixes
[Section titled “Bug Fixes”](#bug-fixes-4)
* **Table image processing**: Fixed Issue #175 - images inside Blogger-style HTML tables (e.g., `<table class="tr-caption-container">`) were being stripped during conversion. Enhanced table scanner to recognize images as content and properly process non-table elements like `<a>` and `<img>` that are direct children of table elements.
* **WASM npm package**: Fixed Issue #172 completely - package was published but missing all WASM binaries and JavaScript wrappers (only 23 KB with 3 files). Created `.npmignore` to include `dist/`, `dist-node/`, and `dist-web/` directories that were excluded by `.gitignore` during npm publish.
* **PHP Packagist publishing**: Fixed version mismatch that caused Packagist to reject v2.19.2 tag. Updated `sync_versions.py` to synchronize both root `composer.json` and `packages/php/composer.json`.
* **Test apps**: Fixed relative fixture paths in C#, Java, and Elixir test apps. Updated Elixir tests to handle tuple-returning API. Added Java native library path configuration.
### Infrastructure
[Section titled “Infrastructure”](#infrastructure-1)
* Enhanced `sync_versions.py` script to update root `composer.json` for Packagist validation
* Recreated v2.19.2 git tag with correct composer.json version
## \[2.19.2] - 2025-12-30
[Section titled “\[2.19.2\] - 2025-12-30”](#2192---2025-12-30)
### Bug Fixes
[Section titled “Bug Fixes”](#bug-fixes-5)
* **WASM npm package**: Fixed missing `.d.ts` files in published package by updating `files` field with glob patterns (fixes #172)
* **Test apps**: Fixed API mismatches across all language test apps (Python, Node.js, WASM, Go, Java, C#)
* Python: Changed `convert_html_to_markdown()` to `convert()`
* Node.js: Updated to scoped package `@kreuzberg/html-to-markdown`
* WASM: Changed `convertHtmlToMarkdown()` to `convert()`
* Go: Updated FFI version from 2.16.0 to 2.19.1 with enhanced error handling
* Java: Added Maven wrapper files for portability
* C#: Updated to `KreuzbergDev.HtmlToMarkdown` package name
* **Packagist publishing**: Added automated workflow job and moved `composer.json` to repository root
* **Maven Central publishing**: Fixed GitHub secrets configuration (corrected `GPG_PASSPHRASE` typo)
* **Go bindings**: Enhanced FFI download error messages with actionable troubleshooting guidance
* **Pre-commit hooks**: Fixed Go linting errors (errcheck, staticcheck) and formatting violations
### Infrastructure
[Section titled “Infrastructure”](#infrastructure-2)
* Created new WASM test app with comprehensive smoke and integration tests
* Updated all test apps to version 2.19.0 for consistent validation
* Enhanced Java package formatting to comply with 120-character line limit
## \[2.19.1] - 2025-12-29
[Section titled “\[2.19.1\] - 2025-12-29”](#2191---2025-12-29)
### Bug Fixes
[Section titled “Bug Fixes”](#bug-fixes-6)
* **Go formatting**: Applied `gofmt` to `packages/go/v2/htmltomarkdown/visitor.go` to align constant declarations
* **Java tooling**: Upgraded google-java-format from 1.21.0 to 1.25.2 for Java 25 compatibility
* **Homebrew distribution**: Added html-to-markdown formula to kreuzberg-dev homebrew tap for CLI installation
## \[2.19.0] - 2025-12-29
[Section titled “\[2.19.0\] - 2025-12-29”](#2190---2025-12-29)
### Breaking Changes
[Section titled “Breaking Changes”](#breaking-changes)
* **npm package namespace**: All npm packages now use the `@kreuzberg` scope for better organization and discoverability
* `html-to-markdown-node` → `@kreuzberg/html-to-markdown-node`
* `html-to-markdown-wasm` → `@kreuzberg/html-to-markdown-wasm`
* **Java package namespace**: Java binding now uses `dev.kreuzberg` package prefix instead of `com.goldziher`
* Updated all Maven artifact IDs and Java package names for semantic clarity
* Affects all public classes and imports in Java projects
* **C# namespace**: C# bindings now use `KreuzbergDev` namespace instead of `Goldziher`
* Updated NuGet package ID to `KreuzbergDev.HtmlToMarkdown`
* All public types now under `KreuzbergDev.HtmlToMarkdown` namespace
### Features
[Section titled “Features”](#features)
* **XML table support (TEI/JATS formats)**: Added support for TEI (Text Encoding Initiative) and JATS (Journal Article Tag Suite) table elements
* `<row>` elements for table rows with proper cell grouping and nesting
* `<cell>` elements with full attribute support including `role="head"` for header cells
* `<graphic>` elements for figure/image references within cells and content blocks
* Proper table structure preservation when converting scientific markup formats
* Aligns with CommonMark table output while respecting source document semantics
### Bug Fixes
[Section titled “Bug Fixes”](#bug-fixes-7)
* Fixed Clippy warnings across Rust core and all binding crates for cleaner compilation
* Improved test suite with enhanced error messages and edge case coverage
* Refined table element handling for robustness with malformed markup
### Infrastructure
[Section titled “Infrastructure”](#infrastructure-3)
* **CI/CD improvements**: Enhanced C# workflow for improved reliability and platform coverage
* **Release distribution**: Added Homebrew bottle support for macOS CLI binary distribution
* **Version synchronization**: All language bindings now synchronized to v2.19.0
## \[2.18.0] - 2025-12-28
[Section titled “\[2.18.0\] - 2025-12-28”](#2180---2025-12-28)
### Added
[Section titled “Added”](#added-13)
* **Visitor Pattern**: Complete implementation of visitor pattern for custom HTML element processing across all 8 language bindings (Python, TypeScript, Ruby, PHP, Go, Java, C#, Elixir)
* Synchronous and asynchronous visitor support (where applicable per language)
* 40+ visitor methods with hooks for every HTML element type (text, links, images, headings, lists, tables, code blocks, and more)
* `NodeContext` provides element metadata: tag name, attributes, depth, parent tag, inline status, and sibling index
* Control flow options: Continue, Custom (provide custom markdown), Skip, PreserveHtml, or Error
* Element lifecycle callbacks: `visit_element_start` and `visit_element_end` for complete control
* **Python**: Full async visitor support with `convert_with_async_visitor()` function
* **TypeScript**: Async visitor with full type definitions
* **Ruby**: Sync visitor implementation with complete RBS type definitions
* **PHP**: Full visitor support with PHPStan level 9 compliance
* **Go**: Thread-safe visitor registry with markdown post-processing
* **Java**: Panama FFI visitor (JDK 21+)
* **C#**: P/Invoke visitor with cross-platform compatibility
* **Elixir**: Rustler NIF visitor implementation
### Fixed
[Section titled “Fixed”](#fixed-42)
* **HTML parsing for modern websites**: Fixed issue where JavaScript-heavy websites (like Reuters) would lose article body content during conversion (GitHub issue #167)
* The parser was incorrectly interpreting HTML-like strings inside `<script>` tags as actual HTML elements
* Script and style tags are now properly stripped during preprocessing while preserving JSON-LD metadata
* No performance impact on conversion speed
* **Python API**: Fixed missing `ConversionOptionsHandle` export in public API (GitHub issue #166)
* Users can now import `ConversionOptionsHandle` directly from the `html_to_markdown` package
* Maintains backward compatibility with existing `OptionsHandle` import
## \[2.17.0] - 2025-12-22
[Section titled “\[2.17.0\] - 2025-12-22”](#2170---2025-12-22)
### Added
[Section titled “Added”](#added-14)
* Go binding now auto-downloads the native FFI library from GitHub Releases with cache/override controls.
* Release pipeline now publishes per-platform Go FFI artifacts for Go installs.
## \[2.16.1] - 2025-12-22
[Section titled “\[2.16.1\] - 2025-12-22”](#2161---2025-12-22)
### Fixed
[Section titled “Fixed”](#fixed-43)
* Fast-path plain-text conversions now honor escape flags (asterisks/underscores/misc/ASCII).
* Fast-path plain-text conversions now normalize whitespace and trim trailing spaces.
* Fast-path plain-text conversions now respect `strip_newlines`.
* Python CLI proxy now only applies v1 translation defaults when v1-only flags are present.
## \[2.16.0] - 2025-12-22
[Section titled “\[2.16.0\] - 2025-12-22”](#2160---2025-12-22)
### Added
[Section titled “Added”](#added-15)
* Profiling harness and workflow for Rust core and bindings with consolidated flamegraph output.
* Benchmark scenarios for inline images, metadata extraction, and raw metadata output across fixtures.
* WASM profiling support with warmups and stable flamegraph parsing.
* FFI byte-based conversion path plus metadata-raw benchmark coverage.
### Changed
[Section titled “Changed”](#changed-11)
* Bench harness now supports expanded fixture coverage and results consolidation.
* Java benchmarks align on JDK 25 for consistent profiling runs.
### Fixed
[Section titled “Fixed”](#fixed-44)
* Node benchmark harness now runs from the package directory and uses native bindings.
* Profiling stability fixes across Go, Elixir, Java, and WASM adapters.
* Binary input detection now flags compressed/magic signatures and UTF-16 data with clearer errors.
### Performance
[Section titled “Performance”](#performance-1)
* Rust core conversion: metadata extraction, inline image handling, tag/whitespace caches, and text assembly hot paths.
* Bindings interop: tighter metadata serialization/deserialization paths.
* Rust bench harness (local, Apple M4): median ops/sec improved 18.8× on Wikipedia fixtures (53.7 → 1009.1).
## \[2.15.0] - 2025-12-19
[Section titled “\[2.15.0\] - 2025-12-19”](#2150---2025-12-19)
### Fixed
[Section titled “Fixed”](#fixed-45)
* Rust core: clamp table `colspan`/`rowspan` to prevent pathological allocations on malformed HTML.
* Rust core: reject binary-like inputs early to avoid OOMs when non-HTML data is passed to `convert`.
## \[2.14.11] - 2025-12-16
[Section titled “\[2.14.11\] - 2025-12-16”](#21411---2025-12-16)
### Fixed
[Section titled “Fixed”](#fixed-46)
* C# (NuGet): fix `ConvertWithMetadata()` deserialization for metadata enums (`link_type`, `image_type`, `data_type`, `text_direction`) by honoring the JSON wire values.
## \[2.14.10] - 2025-12-16
[Section titled “\[2.14.10\] - 2025-12-16”](#21410---2025-12-16)
### Fixed
[Section titled “Fixed”](#fixed-47)
* Python: release the GIL during native conversion so `ThreadPoolExecutor` parallelism doesn’t regress performance, and always build the extension with metadata support (so `convert_with_metadata` is always available).
## \[2.14.9] - 2025-12-16
[Section titled “\[2.14.9\] - 2025-12-16”](#2149---2025-12-16)
### Fixed
[Section titled “Fixed”](#fixed-48)
* Structured data: JSON-LD is now extracted from `<script type="application/ld+json">` tags (including when placed in `<head>`), preserving the script contents for parsing.
## \[2.14.8] - 2025-12-15
[Section titled “\[2.14.8\] - 2025-12-15”](#2148---2025-12-15)
### Fixed
[Section titled “Fixed”](#fixed-49)
* Rust crate (`html-to-markdown-rs`): enable the `metadata` feature by default so `convert_with_metadata` is available without extra Cargo features.
## \[2.14.7] - 2025-12-15
[Section titled “\[2.14.7\] - 2025-12-15”](#2147---2025-12-15)
### Fixed
[Section titled “Fixed”](#fixed-50)
* Elixir (macOS): package now ships a `.cargo/config.toml` so Rustler can compile without requiring user-specific linker flags.
## \[2.14.6] - 2025-12-15
[Section titled “\[2.14.6\] - 2025-12-15”](#2146---2025-12-15)
### Fixed
[Section titled “Fixed”](#fixed-51)
* RubyGems publish: skip duplicate `ruby`-platform gems when multiple CI jobs produce identical artifacts for the same version.
* Hex publish: ensure the Rust core crate is staged into the Elixir package before publishing.
## \[2.14.5] - 2025-12-15
[Section titled “\[2.14.5\] - 2025-12-15”](#2145---2025-12-15)
### Fixed
[Section titled “Fixed”](#fixed-52)
* RubyGems publish: prevent corrupted gem pushes by downloading `rubygems-*` artifacts into separate directories (no merge), and publishing gems recursively with an integrity check.
## \[2.14.4] - 2025-12-15
[Section titled “\[2.14.4\] - 2025-12-15”](#2144---2025-12-15)
### Fixed
[Section titled “Fixed”](#fixed-53)
* Release pipeline: build the C# `osx-x64` native FFI library on `macos-15-intel` (macOS-13 runners are retired), unblocking NuGet publication.
* Elixir (Hex): package now vendors the Rust core crate so `mix deps.get && mix test` works outside this monorepo.
## \[2.14.3] - 2025-12-15
[Section titled “\[2.14.3\] - 2025-12-15”](#2143---2025-12-15)
### Fixed
[Section titled “Fixed”](#fixed-54)
* **Issue #150 / Discord report**: Python now always exports `convert_with_metadata` (no more `ImportError` on import).
* **Issue #149**: Blockquote text now word-wraps when `wrap=true`.
* **FFI JSON parity**: Metadata enums now serialize as snake_case (e.g. `external`, `relative`) to match cross-language expectations.
* PHP test runner now always builds the extension with the `metadata` feature enabled (avoids missing `html_to_markdown_convert_with_metadata` when the workspace was built with `--no-default-features`).
### Added
[Section titled “Added”](#added-16)
* Elixir: `convert_with_metadata/3` + `MetadataConfig` backed by the Rust metadata extractor.
### Changed
[Section titled “Changed”](#changed-12)
* WASM: metadata bindings are enabled by default so the published npm package exports `convertWithMetadata`.
* C# publish pipeline: stage native `html_to_markdown_ffi` libraries into the NuGet package under `runtimes/*/native`.
* Go: module path now uses semantic import versioning (`.../packages/go/v2`), and docs/examples were updated accordingly.
* Java: add `.sdkmanrc` for Java 25 + Maven 4; keep `maven-source-plugin` on `3.3.1` because `4.0.0-beta-1` is not compatible with Maven `4.0.0-rc-4`.
## \[2.14.2] - 2025-12-13
[Section titled “\[2.14.2\] - 2025-12-13”](#2142---2025-12-13)
### Changed
[Section titled “Changed”](#changed-13)
* CI/release automation: extracted Maven installer logic into `scripts/common/install-maven-latest.sh` and applied repo-wide lint/format cleanups.
## \[2.14.1] - 2025-12-12
[Section titled “\[2.14.1\] - 2025-12-12”](#2141---2025-12-12)
### Fixed
[Section titled “Fixed”](#fixed-55)
* **Issue #147**: Word wrap now works correctly in list items when using the `-w`/`--wrap` flag. List items with long text are properly wrapped while preserving list structure and indentation for both ordered and unordered lists.
* **Issue #146**: `strip_tags` and `preserve_tags` options now correctly prevent `<meta>` and `<title>` tags from being extracted into YAML frontmatter when `extract_metadata` is enabled.
* **Issue #145**: `strip_newlines=true` no longer causes excessive whitespace around block elements. Structural whitespace is now properly normalized while still removing newlines within paragraph content.
# Changelog archive: 2.14.0–1.x
## \[2.14.0] - 2025-12-11
[Section titled “\[2.14.0\] - 2025-12-11”](#2140---2025-12-11)
### Added
[Section titled “Added”](#added)
* **CLI Metadata Extraction**: New `--with-metadata` flag with JSON output support for extracting document metadata, headers, links, images, and structured data from HTML documents.
* Six extraction flags: `--extract-document`, `--extract-headers`, `--extract-links`, `--extract-images`, `--extract-structured-data`
* JSON output format with markdown and metadata fields: `{"markdown": "...", "metadata": {...}}`
* Feature enabled by default in CLI builds
* **Go FFI Binding**: Complete `ConvertWithMetadata()` function with typed structs for metadata extraction.
* 12 Go struct types with JSON tags for type-safe metadata access
* JSON unmarshaling from FFI layer
* 18 comprehensive tests covering all metadata types
* **Java FFI Binding**: Complete `convertWithMetadata()` method with Java records for metadata extraction.
* 11 Java record types using Panama FFM for FFI integration
* Proper enum types for link/image/text direction (no string-based parsing)
* Jackson JSON deserialization with error handling
* 33 comprehensive tests including negative test cases
* **C# FFI Binding**: Complete `ConvertWithMetadata()` method with C# records for metadata extraction.
* 11 C# record types using P/Invoke for FFI integration
* System.Text.Json deserialization with proper error handling
* 23 comprehensive tests covering all metadata types
* **FFI Core API**: New `html_to_markdown_convert_with_metadata()` C function for language-agnostic metadata extraction.
* JSON serialization for cross-language compatibility
* Proper memory management and error handling
* 17 comprehensive tests including memory safety tests
### Changed
[Section titled “Changed”](#changed)
* **Documentation Consolidation**: Migrated all standalone METADATA.md files into binding READMEs for improved maintainability.
* Deleted `packages/typescript/METADATA.md` (480 lines) and `packages/ruby/METADATA.md` (228 lines)
* Enhanced Python, PHP, TypeScript, Ruby, Go, Java, and C# READMEs with comprehensive metadata sections
* Root README now includes CLI metadata examples and links to all binding documentation
* Each binding README is now self-contained with full metadata documentation
* **Type Definitions**: Enhanced metadata type definitions across all language bindings.
* Go: Complete struct types with JSON tags and godoc comments
* Java: Proper enum types (LinkType, ImageType, TextDirection) instead of strings
* C#: Complete record types with XML documentation
* Python: Fixed `max_structured_data_size` default (100KB → 1MB)
* TypeScript: Verified dimensions field type (Array for compatibility)
* **Docstrings**: Enhanced documentation strings across all language bindings.
* Rust core: Improved function and module documentation
* Python: Enhanced PyO3 docstrings with examples and type hints
* Ruby: Added YARD tags for better documentation generation
* PHP: Enhanced docblocks with detailed parameter descriptions
### Fixed
[Section titled “Fixed”](#fixed)
* **FFI Memory Safety**: Fixed critical memory safety bug where error paths could leave dangling metadata pointers.
* Both markdown and metadata pointers now set to null on any error
* Added comprehensive memory safety tests
* **CLI Flag Implementation**: Fixed `--extract-document` flag not being mapped to MetadataConfig.
* Flag now correctly controls document metadata extraction
* Added 9 new CLI tests for metadata flags
* **Java Type Safety**: Fixed metadata loss and silent failures from missing fields and string-based enums.
* Added dimensions field to ImageMetadata (was missing, causing 50% metadata loss)
* Changed linkType, imageType, textDirection from String to proper enum types
* Fixed exception swallowing in getLastError() - now logs errors and returns descriptive messages
* **Python Default Values**: Fixed incorrect `max_structured_data_size` default (was 100KB, should be 1MB).
* Now uses `DEFAULT_MAX_STRUCTURED_DATA_SIZE` constant from Rust core
* **Constants Extraction**: Eliminated DRY violations by extracting hardcoded magic numbers.
* Added `DEFAULT_MAX_STRUCTURED_DATA_SIZE: usize = 1_000_000` constant in Rust core
* Reused across FFI, CLI, and Python bindings
### Technical Details
[Section titled “Technical Details”](#technical-details)
* **Test Coverage**: Added 55 new tests across all bindings (71 → 126 total tests, 77% increase)
* FFI: 13 new tests (4 → 17 total)
* CLI: 9 new tests (67 → 76 total)
* Java: 33 new tests (0 → 33 total)
* Go: 18 tests total
* C#: 23 tests total
* **Language Compliance**: Achieved 100% compliance across all bindings (up from 50%-100% range)
* All bindings now correctly implement metadata extraction with proper types
* Standardized error handling and JSON parsing patterns
* **Documentation**: Added 3,500+ lines of comprehensive metadata documentation across all binding READMEs
* Migrated 708 lines from TypeScript and Ruby METADATA.md files
* Enhanced Python and PHP READMEs with extensive examples
* Added metadata sections to Go, Java, and C# READMEs
## \[2.13.0] - 2025-12-10
[Section titled “\[2.13.0\] - 2025-12-10”](#2130---2025-12-10)
### Added
[Section titled “Added”](#added-1)
* Comprehensive metadata extraction API across all language bindings (Python, TypeScript, Ruby, PHP, WASM).
* New `convert_with_metadata()` function returning both markdown and extracted metadata in a single pass.
* Metadata extraction includes: document metadata (title, description, keywords, author, language, Open Graph, Twitter Card), header hierarchy (h1-h6 with IDs and nesting), link classification (internal/external/anchor/email/phone), image metadata with type detection (data URIs, inline SVGs, external, relative), and structured data (JSON-LD, Microdata, RDFa).
* Python: 51 comprehensive integration tests with full TypedDict type stubs and mypy validation.
* TypeScript: 14 vitest tests with auto-generated NAPI types, runtime feature detection via `hasMetadataSupport()`, and 600+ lines of documentation.
* Ruby: 40+ RSpec tests with complete RBS type signatures and comprehensive API documentation.
* PHP: 21 PHPUnit tests with PHPStan level max compliance and readonly Value Objects.
* WASM: Complete metadata extraction with serde_wasm_bindgen serialization and getter/setter configuration structs.
### Changed
[Section titled “Changed”](#changed-1)
* Enabled metadata feature by default in TypeScript and Ruby bindings for production npm packages and gems.
* Updated all language binding versions to 2.13.0 with synchronized version management.
### Fixed
[Section titled “Fixed”](#fixed-1)
* Ruby: Added missing wrapper method for `convert_with_metadata` and fixed redundant `?` symbols in RBS type annotations.
* TypeScript: Enabled metadata feature in default Cargo features to ensure npm packages include metadata functionality.
* WASM: Fixed 3 clippy style violations (Default trait implementation, unwrap_or_default usage, struct initialization pattern).
## \[2.12.1] - 2025-12-09
[Section titled “\[2.12.1\] - 2025-12-09”](#2121---2025-12-09)
### Fixed
[Section titled “Fixed”](#fixed-2)
* Escape literal `|` characters inside table cells while leaving pipes inside `<code>` and `<pre>` untouched to avoid rendering backslashes in code spans/blocks (fixes #140).
* Handle nested tables without double-escaping pipes and add regression coverage for table cells containing code spans/blocks and nested tables.
* Preserve link-only list items when word wrapping is enabled so nested link lists are not merged or reflowed (fixes #143); added regression fixtures for the reported table-of-contents sample.
### Changed
[Section titled “Changed”](#changed-2)
* Updated dependency locks/manifests to align with the 2.12.1 release.
* Downgraded Java Maven compiler/source plugins back to 3.x to keep CI builds compatible with Maven 3 runners.
## \[2.12.0] - 2025-12-08
[Section titled “\[2.12.0\] - 2025-12-08”](#2120---2025-12-08)
### Added
[Section titled “Added”](#added-2)
* WebAssembly bundler target now supports Cloudflare Workers, Wrangler, and modern bundlers that provide `WebAssembly.Module` instead of `WebAssembly.Instance`.
* Three new WASM usage examples demonstrating different deployment targets:
* `examples/wasm-node`: Node.js example using dist-node target
* `examples/wasm-rollup`: Browser example using dist-web target with Rollup
* `examples/wasm-cloudflare`: Cloudflare Workers example using bundler target with Wrangler
### Changed
[Section titled “Changed”](#changed-3)
* WASM bundler entry point now detects and handles `WebAssembly.Module` instances, building the proper import namespace for wasm-bindgen glue functions.
## \[2.11.4] - 2025-12-08
[Section titled “\[2.11.4\] - 2025-12-08”](#2114---2025-12-08)
### Fixed
[Section titled “Fixed”](#fixed-3)
* Node/WASM bundles now post-process their generated JS files to import the shared `WasmConversionOptions` typedef and emit typed doc comments (including typed inline-image `attributes`), so no `any` annotations leak into the published `dist`, `dist-node`, `dist-web`, or docs bundles.
## \[2.11.3] - 2025-12-08
[Section titled “\[2.11.3\] - 2025-12-08”](#2113---2025-12-08)
### Fixed
[Section titled “Fixed”](#fixed-4)
* Prevent link-label truncation from splitting multi-byte characters, which previously triggered a `PanicException` in the Python bindings when processing long anchors (resolves #139) and add a regression test to keep the truncation logic safe.
## \[2.11.2] - 2025-12-07
[Section titled “\[2.11.2\] - 2025-12-07”](#2112---2025-12-07)
### Added
[Section titled “Added”](#added-3)
* Explicitly ship typing artefacts in every binding: npm packages export `.d.ts` files by default, Ruby gems now include `sig/**/*.rbs` even when building outside git, and the Python wheel bundles `_html_to_markdown.pyi` plus a `py.typed` marker for static type checkers.
### Fixed
[Section titled “Fixed”](#fixed-5)
* Cleaned up the Python API’s inline-image helper to avoid redundant casts flagged by `mypy --strict`.
* Tightened PHP docblocks and psalm/phpstan annotations so option arrays use strongly typed shapes instead of `array<string, mixed>`.
* Hardened the WASM, Node, and Python bindings so their `options` argument is fully typed end-to-end (no `any` escapes in `.d.ts` files or placeholder `Any` annotations).
## \[2.11.1] - 2025-12-05
[Section titled “\[2.11.1\] - 2025-12-05”](#2111---2025-12-05)
### Fixed
[Section titled “Fixed”](#fixed-6)
* Preserve indentation in `<pre><code>` blocks while safely dedenting whitespace across multibyte characters to avoid panics when leading spaces are non-ASCII; regression fixture added for issue #134. Thanks @bbeardsley for the contribution.
## \[2.11.0] - 2025-12-04
[Section titled “\[2.11.0\] - 2025-12-04”](#2110---2025-12-04)
### Added
[Section titled “Added”](#added-4)
* CLI `--url` flag with optional `--user-agent` override to fetch remote HTML directly, plus charset-aware decoding.
* New GitHub Pages deploy workflow to publish the `docs/` demo from `main`.
* Additional CLI integration tests covering URL fetching (including custom UA, legacy markup, frameset/noframes, cp1252 decoding).
### Changed
[Section titled “Changed”](#changed-4)
* Demo layout now keeps input/output panes equal height and responsive.
* Rust core handles body-like content accidentally nested in `<head>` more gracefully.
## \[2.10.1] - 2025-12-02
[Section titled “\[2.10.1\] - 2025-12-02”](#2101---2025-12-02)
### Fixed
[Section titled “Fixed”](#fixed-7)
* Normalize whitespace inside link labels (collapse newlines and extra spaces) so anchors with messy HTML do not emit multi-line `[]` text.
* Flatten block children inside `<a>` (e.g., headings/paragraphs nested in anchors) into a single Markdown link instead of duplicating content; regression tests added for the reported Arabic product card case.
### Changed
[Section titled “Changed”](#changed-5)
* Synced all workspace/package versions to 2.10.1 via `task sync-versions`.
## \[2.10.0] - 2025-12-02
[Section titled “\[2.10.0\] - 2025-12-02”](#2100---2025-12-02)
### Added
[Section titled “Added”](#added-5)
* Centralized panic guarding for all bindings (Python, Node, PHP, WASM, C FFI) using a shared Rust helper so panics surface as language-native errors instead of unwinding across FFI boundaries.
* C FFI now stores the last error per thread and exposes it via `html_to_markdown_last_error`, with panic and UTF-8/null input diagnostics.
* Ruby binding now uses the shared panic guard and emits consistent panic messages; specs cover panic interception across conversion entrypoints.
### Changed
[Section titled “Changed”](#changed-6)
* Wasmtime test harness initializes conversion options via struct literals to reduce clippy noise in CI.
### Fixed
[Section titled “Fixed”](#fixed-8)
* Rust coverage CI now forces `cargo-llvm-cov` reinstall to avoid cached binary conflicts on GitHub runners.
* PHP smoke tests use the Packagist package name `goldziher/html-to-markdown`, matching README install instructions.
## \[2.9.3] - 2025-12-01
[Section titled “\[2.9.3\] - 2025-12-01”](#293---2025-12-01)
### Changed
[Section titled “Changed”](#changed-7)
* **Version sync** – Bumped the entire workspace (Rust, Python, npm, Ruby, Elixir, Java, C#, Go) to 2.9.3 via `task sync-versions` to prep the next patch release.
* **Docs & install commands** – Pointed all Composer references to the published `goldziher/html-to-markdown` package and clarified npm usage to the shipped packages (`html-to-markdown-node` / `html-to-markdown-wasm`).
### Fixed
[Section titled “Fixed”](#fixed-9)
* **Go lint CI** – Replaced the invalid `go fmt -l` invocations with `gofmt -l` in the Taskfile so `task check`/CI lint runs complete successfully on Go 1.25.
## \[2.9.2] - 2025-11-28
[Section titled “\[2.9.2\] - 2025-11-28”](#292---2025-11-28)
### Fixed
[Section titled “Fixed”](#fixed-10)
* **UTF-8 safety (Fix #127)** – Guarded whitespace trimming against mid-codepoint truncation, eliminating byte-boundary panics on multilingual documents; added fixture and regression test for the reported Ruby-path crash.
* **Image conversion (Fix #128)** – `<img>` elements with `width`/`height` now render as Markdown images instead of raw HTML; regression test covers inline-data URIs with dimensions.
## \[2.9.1] - 2025-11-22
[Section titled “\[2.9.1\] - 2025-11-22”](#291---2025-11-22)
### Changed
[Section titled “Changed”](#changed-8)
* **HTML repair fallback** – Minified or malformed pages now reparse via html5ever when inline/block nesting is broken, keeping content that previously vanished (e.g., SPA shells and Hacker News markup).
* **Link label recovery** – Anchor text fallback prefers child formatting or hrefs only when appropriate, preventing empty labels while keeping CommonMark empty-link semantics intact.
### Fixed
[Section titled “Fixed”](#fixed-11)
* **Layout tables to lists** – Headless tables with mixed column counts/spans or nested tables render as list rows instead of broken Markdown tables, restoring Hacker News output.
* **Issue 121 regressions** – Added fixtures/tests for the empty SPA and malformed Hacker News samples; both now produce full Markdown content without frontmatter noise.
## \[2.9.0] - 2025-11-20
[Section titled “\[2.9.0\] - 2025-11-20”](#290---2025-11-20)
### Added
[Section titled “Added”](#added-6)
* **Elixir bindings** – New `html_to_markdown` Hex package built with Rustler, exposing the Rust core converter to Elixir with configurable options plus `convert/2` and `convert!/2`.
* **WASM runtime verification** – Added a Wasmtime-backed e2e suite (`e2e/wasm-wasmtime`) plus `task wasm:test:wasmtime` to compile the `html-to-markdown-wasm` artefact for `wasm32-unknown-unknown` and execute it inside Wasmtime. CI now runs these tests to ensure the WASM package works outside the browser runtime.
### Changed
[Section titled “Changed”](#changed-9)
* **Astral `tl` parser** – The HTML parser dependency now points to the actively maintained `astral-tl` fork (still imported as `tl`) so comment parsing stays up to date with upstream fixes.
* **NuGet Package ID** – C# bindings now publish under `Goldziher.HtmlToMarkdown` to avoid clashing with an existing community package.
* **Wasmtime CI Coverage** – The Wasmtime e2e job now runs on Linux x64, Linux arm64, macOS, and Windows runners so every GitHub-hosted architecture executes the WASM tests.
### Fixed
[Section titled “Fixed”](#fixed-12)
* **PHP PIE source bundle** – Release packaging strips the Wasmtime e2e workspace from the staged `Cargo.toml`, fixing the “failed to load manifest” error in the publish workflow.
* **Horizontal rule rendering** – `<p>…</p><hr>` now emits a blank line before `---` while preserving blockquote spacing so the rule is never misinterpreted as a setext heading.
* **Empty HTML comments** – Zero-width `<!---->` comment nodes are normalized before parsing, so comment placeholders no longer cause the following content to disappear.
## \[2.8.3] - 2025-11-15
[Section titled “\[2.8.3\] - 2025-11-15”](#283---2025-11-15)
### Changed
[Section titled “Changed”](#changed-10)
* **Deterministic uv installs** – Every `uv sync` invocation in CI and the Taskfile now runs with `--no-install-workspace`, ensuring Python dependencies are resolved without mutating editable installs before the subsequent build/test steps run.
### Fixed
[Section titled “Fixed”](#fixed-13)
* **NuGet Publishing** – Release automation now uses GitHub’s trusted publisher flow via `NuGet/login@v1` (OIDC → short-lived API key) before pushing artifacts, removing the dependency on long-lived secrets.
* **Hex Publishing** – The release workflow invokes `mix hex.publish --yes` from `packages/elixir`, with `ex_doc` bundled as a dev dependency so documentation generation works during release.
## \[2.8.2] - 2025-11-15
[Section titled “\[2.8.2\] - 2025-11-15”](#282---2025-11-15)
### Changed
[Section titled “Changed”](#changed-11)
* **Unified Version Sync** – `scripts/sync_versions.py` now updates Elixir `@version` declarations, the C# `.csproj`, and the Java `pom.xml` (alongside every npm/pyproject/Gemfile manifest). `task sync-versions` bumps the entire multi-language stack to **2.8.2** in one shot.
* **CI / Release Toolchains** – GitHub Actions now installs Elixir dependencies ahead of Credo and runs on **Elixir 1.19 + OTP 28.1**, matching the README prerequisites and preventing per-job regex recompilation warnings.
* **Taskfile Coverage** – Added `elixir:update` plus full `java:{install,update,test,lint}` tasks so `task setup`, `task update`, `task test`, and `task lint` cover every published runtime (Go, C#, Elixir, Java) just like the CI workflows.
## \[2.8.1] - 2025-11-15
[Section titled “\[2.8.1\] - 2025-11-15”](#281---2025-11-15)
### Fixed
[Section titled “Fixed”](#fixed-14)
* **Release Pipeline** – Bumped all package manifests to v2.8.1 so the publish workflow can push fresh artifacts after the v2.8.0 smoke-test fixes (PyPI, npm, and RubyGems refuse re-uploads of the same version).
## \[2.8.0] - 2025-11-15
[Section titled “\[2.8.0\] - 2025-11-15”](#280---2025-11-15)
### Added
[Section titled “Added”](#added-7)
* **Java, C#, and Go Bindings (First Release)** – First public release of official Java (JNA), C# (.NET), and Go (CGO) language bindings. All three are integrated into the unified `task bench:bindings` harness and ship with comprehensive performance data in their READMEs. C# leads at \~1.4k ops/sec (≈171 MB/s), Go at \~1.3k ops/sec (≈165 MB/s), and Java at \~1.0k ops/sec (≈126 MB/s) on the 129 KB Wikipedia lists fixture.
### Changed
[Section titled “Changed”](#changed-12)
* **BREAKING: Preprocessing Disabled by Default** – HTML preprocessing is now disabled by default in the library API to prevent silent content loss. Previously, `<nav>`, `<form>`, and related elements (along with all their children) were dropped by default, causing important content inside these tags to be lost. Users who want preprocessing must now explicitly enable it via `PreprocessingOptions { enabled: true, ... }`. The CLI behavior is unchanged (preprocessing has always been opt-in with `--preprocess`).
* **Rust Toolchain Settings** – All crates (including the Ruby binding) now inherit `edition = "2024"` and `rust-version = "1.85"` from the workspace to keep toolchain configuration centralized.
* **GitHub Actions Workflow DRY** – Created 17 reusable composite actions (8 build actions + 9 smoke test actions) to eliminate \~267 lines of duplication between CI and publish workflows.
* **Toolchain Management** – Migrated to official GitHub Actions parameters for Ruby Bundler 2.7.2 and PHP Composer 2.9.1, removing manual installation scripts.
### Fixed
[Section titled “Fixed”](#fixed-15)
* **Windows PHP Extension Build** – Replaced php-windows-builder orchestration with direct `cargo build` matching ext-php-rs’s proven approach, resolving LLVM 19 MMX header incompatibilities and Zend symbol linking errors.
* **Linux PHP Build** – Added php-config path capture and parameter passing to build-php-linux action, fixing “php-config executable not found” errors.
* **Ruby Linux Build** – Set LD_LIBRARY_PATH on Linux builds to match magnus best practices, preventing potential “strings.h not found” errors.
* **golangci-lint CI** – Split golangci-lint pre-commit hook into separate invocations for `packages/go` and `examples/go-smoke` modules, fixing “directory prefix does not contain main module” errors by running each check from within its Go module directory.
* **Windows Go CGO Smoke Test** – Documented MSVC/MinGW toolchain incompatibility and skip Windows Go smoke test with informative message, as Go CGO uses MinGW which cannot link against MSVC-compiled Rust FFI libraries.
* **Go Code Quality** – Removed redundant newline in `examples/go-smoke/main.go` fmt.Println call (detected by newly-working golangci-lint).
## \[2.7.2] - 2025-11-12
[Section titled “\[2.7.2\] - 2025-11-12”](#272---2025-11-12)
### Fixed
[Section titled “Fixed”](#fixed-16)
* **Node/WASM Binding Regression** – HTML preprocessing no longer drops `<html>`, `<head>`, or `<body>` wrappers when their classes resemble navigation chrome, so large Wikipedia fixtures once again emit full markdown (restoring the Vitest length/table expectations for Node bindings and keeping WASM conversions consistent).
* **Cloudflare WASM Initialization** – Bundler builds of `html-to-markdown-wasm` now expose `initWasm()`/`wasmReady` so edge runtimes that instantiate WebAssembly modules asynchronously (Cloudflare Workers, Vite dev servers, etc.) can await initialization before calling `convert()`, eliminating the `__wbindgen_start` runtime error.
* **Footer Retention (Fix #120)** – The Rust preprocessor keeps plain `<footer>` content unless the element carries explicit navigation hints (role/class/id). Python and Rust conversions once again preserve footer copy while still stripping true navigation footers such as `.site-footer` menus.
* **Release Smoke Coverage** – The publish workflow now downloads the built artifacts (Node, WASM, Python wheels, Ruby gems, PHP zips) and reruns the README smoke installs across Linux/macOS/Windows before any packages are uploaded, ensuring we’re testing the exact bits we ship.
## \[2.7.1] - 2025-11-12
[Section titled “\[2.7.1\] - 2025-11-12”](#271---2025-11-12)
### Added
[Section titled “Added”](#added-8)
* **Language-Specific Benchmarks** – Every binding README (Node, WASM, Python, Ruby, PHP, TypeScript) now publishes the latest `task bench:bindings` throughput numbers so runtime documentation stays aligned with the shared fixtures.
* **Examples/Smoke Suite** – Added `examples/{node,wasm,python,ruby,php,rust}-smoke` plus an overview README to exercise both the published artifacts and local builds before a release.
### Changed
[Section titled “Changed”](#changed-13)
* **Docs Accuracy** – Node/WASM READMEs now clearly reference the real npm packages (`html-to-markdown-node`, `html-to-markdown-wasm`) and provide correct import samples.
* **TypeScript README** – Highlights that the CLI wrapper inherits the native Node benchmarks.
* **Repository Hygiene** – `.gitignore` now drops `.venv/`, vendor directories, and nested `node_modules/` so smoke tests and language-specific toolchains don’t dirty the tree.
* **Ruby Build Metadata** – `extconf.rb` uses a relative path for the embedded Cargo crate and the crate’s `Cargo.toml` now declares explicit `edition`, `rust-version`, and dependency pins, allowing `gem install` outside the workspace.
* **Version Sync Script** – `scripts/sync_versions.py` updates every `html-to-markdown-rs` dependency pin (workspace root plus downstream crates) to keep cross-language releases in lockstep.
### Fixed
[Section titled “Fixed”](#fixed-17)
* **Smoke Test Coverage** – Verified Node, WASM, Python, Ruby (local gem), PHP (Composer path repo), and Rust installs; documented gaps where external registries still need to publish `goldziher/html-to-markdown` or `html-to-markdown` 2.7.1 before release.
## \[2.7.0] - 2025-11-12
[Section titled “\[2.7.0\] - 2025-11-12”](#270---2025-11-12)
### Added
[Section titled “Added”](#added-9)
* **Zero-Copy Inline Images** – Node/N-API and WASM bindings now expose `convertInlineImagesBuffer` / `convertBytesWithInlineImages`, letting benchmark harnesses feed `Buffer`/`Uint8Array` data directly without creating intermediate JS strings.
### Changed
[Section titled “Changed”](#changed-14)
* **Rust Core Preprocessing** – HTML normalization (self-closing fixes, malformed `<` escaping, script/style stripping) now happens in a single streaming pass that hands owned buffers straight to `tl::parse_owned`, cutting multiple allocations from every conversion.
* **Benchmark Harness + Docs** – Re-ran the cross-language runtime suite after the Rust core optimizations and refreshed the README tables, keeping the published throughput numbers (Node/Python/Rust/WASM/PHP) in sync with `tools/runtime-bench/results/latest.json`.
* **Version Alignment** – Bumped every package (Rust crates, npm packages, PyPI distribution, Ruby gem, PHP extension, WASM bundle) to `2.7.0` via `task sync-versions`.
### Fixed
[Section titled “Fixed”](#fixed-18)
* **Ruby Benchmark Output** – The Ruby benchmark driver now emits JSON without relying on `json` native extensions, preventing `libruby` incompatibility errors during `task bench:bindings`.
* **Nested `<strong>` Normalization (Fix #111)** – The Rust converter now tracks when bold markup is already active, so nested `<b>`/`<strong>` combinations (including `<mark>`, `<summary>`, `<legend>`) no longer generate `****` artifacts (`<b>bo<b>ld</b>er</b>` correctly becomes `**bolder**`). The CommonMark harness documents the four spec examples that expect stacked markers and skips them accordingly.
* **Heading Whitespace (Fix #118)** – ATX/Setext headings swallow layout-only newlines and indentation inside `<h1>…<h6>` so pretty-printed HTML like `<h2>Heading\n Text</h2>` renders as a single Markdown heading line.
* **Inline Whitespace Preservation** – Reworked the inline text pipeline so removing zero-width inline elements (e.g., `<input>`, `<script>`, empty `<b>`) no longer collapses surrounding spaces; fixtures like `test_chomp`, `test_form_with_inputs_inline_mode`, and checkbox/task-list rendering now match their expected double-space gaps.
* **DOCTYPE Handling (Fix #119)** – `<!DOCTYPE …>` declarations are stripped during preprocessing so they never leak as stray `PUBLIC…` text in the output, even when metadata extraction is enabled.
## \[2.6.6] - 2025-11-10
[Section titled “\[2.6.6\] - 2025-11-10”](#266---2025-11-10)
### Changed
[Section titled “Changed”](#changed-15)
* **Ruby Gem Packaging** – Moved the `html-to-markdown-rb` crate under `packages/ruby/ext/html-to-markdown-rb/native` and pointed `extconf.rb` at that path so every published gem now contains the Cargo sources it needs to compile on install.
* **Documentation Consistency** – Updated the root, crate, and package READMEs to drop references to the unrelated `html-to-markdown` npm package and to consistently list our supported targets (Node, WASM, Python, Ruby, PHP, CLI).
* **Dependency Refresh** – Ran `task update` to upgrade Rust crates, npm packages, Bundler gems, Python requirements, and Composer dependencies across the monorepo.
### Fixed
[Section titled “Fixed”](#fixed-19)
* **Rust Clippy Lints** – Addressed `clippy::unnecessary-map-or` in the converter and hOCR table builder by using `.is_none_or`, keeping inline-image filtering and column pruning logic clear while allowing `cargo clippy -D warnings` to pass.
* **PIE Source Packaging** – `scripts/package_php_pie_source.sh` now copies `packages/ruby/.../native` into the temporary workspace so the Ruby crate exists when PIE builds the PHP extension.
## \[2.6.3] - 2025-11-07
[Section titled “\[2.6.3\] - 2025-11-07”](#263---2025-11-07)
### Fixed
[Section titled “Fixed”](#fixed-20)
* **Release Pipeline** - Fixed missing `is_tag` output in publish workflow that caused all publishing jobs to be skipped
* **Node.js Package Dependencies** - Added missing `optionalDependencies` to html-to-markdown-node package.json to properly link platform-specific binaries
* **Version Management** - Created centralized version sync script (`scripts/sync_versions.py`) to maintain consistency across all package manifests (Rust, Node.js, Python, Ruby, WASM)
* **Cargo Workspace** - Aligned html-to-markdown-rb crate version (was 2.5.7) with workspace version
### Changed
[Section titled “Changed”](#changed-16)
* Added `task sync-versions` command to Taskfile for easy version synchronization across the monorepo
## \[2.6.2] - 2025-11-07
[Section titled “\[2.6.2\] - 2025-11-07”](#262---2025-11-07)
### Fixed
[Section titled “Fixed”](#fixed-21)
* **Table Rowspan Support** - Fixed tables with rowspan cells to correctly duplicate cell content across spanned rows instead of showing empty cells (fixes #116)
* **Node.js Platform Package Publishing** - Fixed workflow to correctly move packed .tgz files to npm directory for publishing
* **Deprecation Warnings** - Updated CLI tests to use `CARGO_BIN_EXE` env var instead of deprecated `cargo_bin` method
* **Deprecation Warnings** - Replaced deprecated `criterion::black_box` with `std::hint::black_box` in benchmarks
* **Clippy Warnings** - Fixed field assignment warnings by using struct initialization with defaults
## \[2.6.1] - 2025-11-07
[Section titled “\[2.6.1\] - 2025-11-07”](#261---2025-11-07)
### Fixed
[Section titled “Fixed”](#fixed-22)
* **Node.js Platform Packages** - Fixed publishing of platform-specific npm packages. The workflow now correctly packs npm directories into .tgz files before publishing, ensuring all platform bindings (linux-x64-gnu, darwin-arm64, win32-x64-msvc, etc.) are published to npm.
* **WASM Package Publishing** - Added proper WASM package publishing workflow to ensure html-to-markdown-wasm is published to npm registry.
## \[2.6.0] - 2025-11-07
[Section titled “\[2.6.0\] - 2025-11-07”](#260---2025-11-07)
### Added
[Section titled “Added”](#added-10)
* **PHP Extension Support** - Official PHP extension (`goldziher/html-to-markdown`) providing native HTML to Markdown conversion for PHP 8.2+
* Built with ext-php-rs for high-performance Rust-backed conversion
* Supports both Thread-Safe (TS) and Non-Thread-Safe (NTS) builds
* Available for Windows (x86, x64), Linux, and macOS
* Distributed via PIE (PHP Installer for Extensions) source bundles
* Prebuilt Windows binaries for PHP 8.2, 8.3, and 8.4
* Comprehensive test suite with PHPUnit
### Changed
[Section titled “Changed”](#changed-17)
* Refactored PHP build variable names from `HTM2MD_*` to `HTMLTOMARKDOWN_*` for improved clarity in Makefile.frag and config.m4
* Bumped all package versions to 2.6.0 across Rust crates, npm packages, PyPI wheels, Ruby gem, and PHP extension
## \[2.5.7] - 2025-11-03
[Section titled “\[2.5.7\] - 2025-11-03”](#257---2025-11-03)
### Added
[Section titled “Added”](#added-11)
* Publish Windows PHP extension binaries alongside the PIE source bundle during the release pipeline, enabling one-click installs on every platform.
* Build and archive the CLI binary for Linux (gnu & musl), macOS arm64, and Windows x86_64, plus ship prebuilt WASM bundles (dist/dist-node/dist-web) so every runtime gets first-class artifacts.
### Changed
[Section titled “Changed”](#changed-18)
* Renamed the PHP extension package to `goldziher/html-to-markdown`, moved the Composer metadata to the repository root, and refreshed the documentation/badges for every language target.
* Bumped every package (Rust crates, npm packages, PyPI wheels, Ruby gem, PHP extension) to version 2.5.7.
* Restored the Node.js N-API build matrix so macOS, Windows, and Linux binaries ship automatically with each npm release.
### Fixed
[Section titled “Fixed”](#fixed-23)
* Preserve ordered list numbering and indentation when list items render headings or HTML tables, so mixed block content stays under the correct bullet (fixes #107).
## \[2.5.6] - 2025-10-30
[Section titled “\[2.5.6\] - 2025-10-30”](#256---2025-10-30)
### Changed
[Section titled “Changed”](#changed-19)
* The Ruby gem now packages its own README at the gem root, so RubyGems renders the fully formatted documentation (benchmarks, configuration, CLI notes) without broken links.
* Documentation links: the Ruby README now surfaces GitHub resources (issues, changelog, live demo) alongside feature highlights.
* Bumped every package (Rust crates, npm, PyPI, Ruby gem) to version 2.5.6.
## \[2.5.5] - 2025-10-30
[Section titled “\[2.5.5\] - 2025-10-30”](#255---2025-10-30)
### Changed
[Section titled “Changed”](#changed-20)
* Synced documentation: the root README now links to every language guide, and the Ruby README highlights GitHub resources alongside feature docs.
* Gem packaging now reads the README directly for the RubyGems long description while keeping Rubocop happy on all Ruby sources.
* Bumped every package (Rust crates, npm, PyPI, Ruby gem) to version 2.5.5.
## \[2.5.4] - 2025-10-30
[Section titled “\[2.5.4\] - 2025-10-30”](#254---2025-10-30)
### Changed
[Section titled “Changed”](#changed-21)
* Polished the Ruby gem messaging and README with performance highlights, configuration examples, and CLI guidance to match other language docs.
* Bumped every package (Rust crates, npm, PyPI, Ruby gem) to version 2.5.4.
## \[2.5.3] - 2025-10-30
[Section titled “\[2.5.3\] - 2025-10-30”](#253---2025-10-30)
### Changed
[Section titled “Changed”](#changed-22)
* Publish Ruby gems as precompiled artifacts for Linux (x86_64), macOS (arm64 & x86_64), and Windows (x64) via a matrix GitHub Action, ensuring the CLI executable matches the target platform.
* Split the release workflow into prepare/build/publish stages so dry runs build artifacts without pushing, and trusted publishing now uploads every generated `.gem`.
* Hardened the gem preparation script to clear stale CLI binaries before copying in the platform-specific build output.
* Re-enabled the cross-language release workflow so crates.io, PyPI wheels/sdist, and both npm packages ship alongside the Ruby release.
## \[2.5.2] - 2025-10-29
[Section titled “\[2.5.2\] - 2025-10-29”](#252---2025-10-29)
* Fix Ruby gem packaging to embed standalone Cargo manifest (no workspace inheritance) so installs compile out of tree successfully.
* Bump versions across Rust, Node, Python, and Ruby bindings.
## \[2.5.1] - 2025-10-28
[Section titled “\[2.5.1\] - 2025-10-28”](#251---2025-10-28)
### Added
[Section titled “Added”](#added-12)
* Magnus-based Ruby gem (`html-to-markdown-rb`) with CLI proxy and comprehensive specs.
### Changed
[Section titled “Changed”](#changed-23)
* CI now includes Ruby coverage across macOS, Linux, and Windows, installing the appropriate toolchains (MSYS2 on Windows) for Magnus builds.
* Release workflow prepares the Ruby gem via trusted publishing alongside existing crates/npm packages.
### Fixed
[Section titled “Fixed”](#fixed-24)
* Bundler version pinned to 2.5.12 to support Ruby 3.2 CI environments.
## \[2.5.0] - 2025-10-24
[Section titled “\[2.5.0\] - 2025-10-24”](#250---2025-10-24)
### Added
[Section titled “Added”](#added-13)
* **New `preserve_tags` option** - Preserve specific HTML tags in their original HTML form instead of converting them to Markdown. This is useful for complex elements like tables that may not convert well to Markdown. Fixes issue #95.
* Accepts a list of tag names (e.g., `["table", "form"]`)
* Preserves all attributes and nested content as HTML
* Works independently of `strip_tags` - can use both options together
* Available in all bindings: Rust, Python, Node.js, and WASM
* Comprehensive test coverage in Rust, Python (pytest), and TypeScript (vitest)
### Changed
[Section titled “Changed”](#changed-24)
* **HTML preprocessing is now enabled by default** - The `PreprocessingOptions.enabled` default changed from `False` to `True` to ensure robust handling of malformed HTML. Users who want minimal preprocessing can explicitly set `enabled=False`.
### Fixed
[Section titled “Fixed”](#fixed-25)
* **Task list checkbox support** - Fixed sanitizer removing `<input type="checkbox">` elements when `remove_forms` is enabled (default). Checkboxes are now preserved during preprocessing to enable proper task list conversion (`- [x]` / `- [ ]`).
* Added `input` tag to allowed tags in all sanitization presets (minimal, standard, aggressive)
* Preserved `type` and `checked` attributes on input elements
* Fixed pre-existing bug where task list checkboxes were silently removed
* **Data URI support for inline images** - Fixed sanitizer stripping `data:` URLs from image src attributes. Base64-encoded inline images (data URIs) are now preserved during preprocessing.
* Added `data` to allowed URL schemes in all sanitization presets
* Fixes `convert_with_inline_images` functionality for base64-encoded images
* **CDATA section handling** - Fixed test expectation for CDATA sections. CDATA sections are now correctly preserved as-is during HTML parsing instead of being partially stripped.
* **hOCR word spacing** - Fixed missing whitespace between `<span class="ocrx_word">` elements in hOCR documents. Words now have proper spaces between them.
* Modified `OcrxWord` converter to insert space before each word if output doesn’t end with whitespace or markdown formatting characters
* Ensures proper word separation in OCR-generated documents without breaking markdown formatting (e.g., `*text*`, `[alt](url)`, `` `code` ``)
* **hOCR detection with preprocessing** - Fixed hOCR documents not being detected when HTML preprocessing is enabled (new default). The sanitizer now preserves:
* `class` attributes on all elements (required for detecting hOCR element types)
* `<meta>` tags with `name` and `content` attributes (required for hOCR metadata detection)
* `<head>` tags (container for meta tags)
* **hOCR metadata extraction after sanitization** - Fixed metadata extraction failing when preprocessing strips the `<head>` container element. The extractor now finds orphaned meta tags anywhere in the document, not just inside `<head>` elements.
* **`preserve_tags` functionality with preprocessing** - Fixed `preserve_tags` not working when HTML preprocessing is enabled (the new default). The sanitizer now:
* Accepts the `preserve_tags` list and allows those tags through sanitization
* Preserves common HTML attributes (`id`, `class`, `style`, `title`, etc.) on preserved tags
* Prevents `remove_forms` from stripping form tags when they’re in the preserve list
* Ensures tags and attributes survive preprocessing so they can be output as HTML
* **SVG support for inline image extraction** - Fixed SVG elements being stripped by the sanitizer, breaking inline image capture. All sanitization presets now allow:
* SVG elements: `svg`, `circle`, `rect`, `path`, `line`, `polyline`, `polygon`, `ellipse`, `g`
* SVG attributes: `width`, `height`, `viewBox`, `cx`, `cy`, `r`, `x`, `y`, `d`, `fill`, `stroke`
* Enables `convert_with_inline_images` to capture inline SVG elements
* **Robust handling of malformed angle brackets in HTML** - Fixed parser failures when bare `<` or `>` characters appear in HTML text content (e.g., `1<2`, mathematical comparisons). The converter now:
* Automatically escapes malformed angle brackets that aren’t part of valid HTML tags
* Works correctly with preprocessing both enabled and disabled
* Handles edge cases like `1<2`, `1 < 2 < 3`, and angle brackets at tag boundaries
* Fixes issue #94 where content following malformed angle brackets was lost
* Added comprehensive test coverage for malformed angle bracket handling in both Rust and Python test suites
* Fixed WASM build configuration to use correct `getrandom` backend for wasm32-unknown-unknown targets
## \[2.4.1] - 2025-10-22
[Section titled “\[2.4.1\] - 2025-10-22”](#241---2025-10-22)
### Fixed
[Section titled “Fixed”](#fixed-26)
* Ensure npm publishes include the generated Node bindings and platform binaries by running the N-API build during CI.
* Configure WebAssembly builds with the `wasm_js` backend and strip wasm-pack `.gitignore` files so published packages ship the compiled `.wasm` artifacts.
## \[2.4.0] - 2025-10-22
[Section titled “\[2.4.0\] - 2025-10-22”](#240---2025-10-22)
### Changed
[Section titled “Changed”](#changed-25)
* Updated Rust workspace dependencies (including `pyo3`) to their latest compatible releases and refreshed lockfiles.
* Normalized hOCR conversion spacing by collapsing stray triple newlines, ensuring generated Markdown matches regression fixtures.
### Fixed
[Section titled “Fixed”](#fixed-27)
* Corrected the WASM crate to depend on `getrandom`’s `wasm_js` feature, restoring WebAssembly builds.
* Expanded the Node package `files` list so published tarballs now include compiled `.node` artifacts, CommonJS shims, and typings.
## \[2.3.4] - 2025-10-12
[Section titled “\[2.3.4\] - 2025-10-12”](#234---2025-10-12)
### Changed
[Section titled “Changed”](#changed-26)
* Incremented all distribution metadata and CLI version checks to 2.3.4 following the previous release tag conflict.
* Regenerated package metadata artifacts for the new patch release.
## \[2.3.3] - 2025-10-12
[Section titled “\[2.3.3\] - 2025-10-12”](#233---2025-10-12)
### Added
[Section titled “Added”](#added-14)
* Python API now exports inline image helpers (`InlineImage`, `InlineImageWarning`, and `InlineImageConfig`) alongside `convert_with_inline_images`, with dedicated regression tests.
* Node and WASM bindings include inline image extraction examples and TypeScript definitions, validated by Vitest coverage.
### Changed
[Section titled “Changed”](#changed-27)
* Bumped all package metadata (Python, Rust, Node, WASM, CLI) to version 2.3.3 for a synchronized release.
### Fixed
[Section titled “Fixed”](#fixed-28)
* CLI `--version` test updated to assert the new release number.
## \[2.2.0] - 2025-10-11
[Section titled “\[2.2.0\] - 2025-10-11”](#220---2025-10-11)
### Added
[Section titled “Added”](#added-15)
* `hocr_spatial_tables` option on `ConversionOptions` (Rust, Python, CLI) with `--no-hocr-spatial-tables` flag to disable spatial table reconstruction when desired.
* New hOCR regression fixtures for complex tables and code blocks to guard against formatting regressions.
### Changed
[Section titled “Changed”](#changed-28)
* Improved hOCR conversion heuristics to distinguish between dense paragraph layouts and true tables, yielding cleaner Markdown for scientific data.
* hOCR code-block detection now preserves fenced formatting, restoring context headings when present.
### Fixed
[Section titled “Fixed”](#fixed-29)
* CLI `--version` output and package metadata now report version 2.2.0 consistently.
## \[2.1.1] - 2025-10-11
[Section titled “\[2.1.1\] - 2025-10-11”](#211---2025-10-11)
### Fixed
[Section titled “Fixed”](#fixed-30)
* Improve hOCR table reconstruction when tables are represented as paragraphs, ensuring Markdown tables are emitted for Tesseract outputs without explicit `ocr_table` markers.
## \[2.1.0] - 2025-10-11
[Section titled “\[2.1.0\] - 2025-10-11”](#210---2025-10-11)
### Added
[Section titled “Added”](#added-16)
* **Inline image extraction** - New `convert_with_inline_images()` function to extract embedded images during conversion
* Supports data URI images (`data:image/*`)
* Supports inline SVG elements
* Configurable via `InlineImageConfig` with options for:
* Maximum decoded size limits
* Custom filename prefixes
* SVG capture control
* Optional dimension inference for raster images
* Returns `HtmlExtraction` with markdown, extracted images, and warnings
* Available through both Rust and Python APIs
### Changed
[Section titled “Changed”](#changed-29)
* **Simplified API** - Removed `ParsingOptions` class in favor of direct `encoding` parameter on `ConversionOptions`
* **Automatic hOCR table extraction** - hOCR tables are now extracted automatically without requiring configuration
* Removed `hocr_extract_tables` option (always enabled for hOCR content)
* Removed `hocr_table_column_threshold` option (uses built-in heuristics)
* Removed `hocr_table_row_threshold_ratio` option (uses built-in heuristics)
* Updated pre-commit hook versions (commitlint v9.23.0, pyproject-fmt v2.10.0, ruff v0.14.0)
### Fixed
[Section titled “Fixed”](#fixed-31)
* **hOCR metadata now uses YAML frontmatter** instead of HTML comments for cleaner markdown output
* **hOCR code organization** - Restructured spatial table reconstruction into dedicated `hocr/spatial.rs` module
* **Conservative table detection** - hOCR spatial table reconstruction now only applies to explicit `ocr_table` elements, preventing false positives
* Windows CLI binary detection - now correctly searches for `.exe` extension on Windows
* CLI binary bundling in Python wheels - binary now included in package for all platforms
* hOCR extractor Rust doctest - added missing import statement
* 928 Python test expectations updated for CommonMark-compliant v2 defaults
* Python 3.14-dev → Python 3.14 stable in CI workflows
* Reorganized wheel preparation script to `scripts/` directory
* Removed duplicate markdown documentation files (BENCHMARKS.md, PERFORMANCE.md, BENCHMARK_RESULTS.md, COMMONMARK_COMPLIANCE.md, REFACTORING_SUMMARY.md)
## [2.0.0](https://github.com/xberg-io/html-to-markdown/compare/v1.x...v2.0.0) - 2025-10-03
[Section titled “2.0.0 - 2025-10-03”](#200---2025-10-03)
### Major Rewrite: Rust Backend
[Section titled “Major Rewrite: Rust Backend”](#major-rewrite-rust-backend)
Version 2.0.0 represents a complete rewrite of html-to-markdown with a high-performance Rust backend, delivering **10-30x performance improvements** while maintaining full backward compatibility through a v1 compatibility layer.
### ⚠️ Breaking Changes
[Section titled “⚠️ Breaking Changes”](#️-breaking-changes)
#### CommonMark-Compliant Defaults
[Section titled “CommonMark-Compliant Defaults”](#commonmark-compliant-defaults)
V2 adopts CommonMark-compliant defaults for better interoperability:
| Option | V1 Default | V2 Default | Reason |
| ----------------------- | ------------ | ---------- | -------------------------------- |
| `list_indent_width` | 4 | 2 | CommonMark standard |
| `bullets` | “-” | “\*+-” | Cycling bullets for nested lists |
| `escape_asterisks` | true | false | Minimal escaping |
| `escape_underscores` | true | false | Minimal escaping |
| `escape_misc` | true | false | Minimal escaping |
| `newline_style` | “backslash” | “spaces” | CommonMark two-space line breaks |
| `code_block_style` | “backticks” | “indented” | CommonMark 4-space indent |
| `heading_style` | “underlined” | “atx” | CommonMark `#` headings |
| `preprocessing.enabled` | false | false | No change (opt-in) |
**Migration**: If you relied on v1 defaults, explicitly set options to match v1 behavior.
#### Removed CLI Flags
[Section titled “Removed CLI Flags”](#removed-cli-flags)
The following v1 CLI flags are **not supported** in v2. The Python CLI proxy will raise helpful error messages when these flags are used:
| Removed Flag | Reason | Migration |
| ------------ | --------------------- | ----------------------------------------- |
| `--strip` | Feature removed in v2 | Remove flag (feature no longer available) |
| `--convert` | Feature removed in v2 | Remove flag (feature no longer available) |
**Note on Redundant Flags**: The following v1 flags are redundant in v2 (they match the defaults) but are **silently accepted** for backward compatibility:
* `--no-escape-asterisks`, `--no-escape-underscores`, `--no-escape-misc` (v2 defaults to minimal escaping)
* `--no-wrap` (v2 defaults to no wrapping)
* `--no-autolinks` (Rust CLI defaults to no autolinks)
* `--no-extract-metadata` (Rust CLI defaults to no metadata extraction)
These flags can be safely removed from your commands, or you can leave them for compatibility.
**Note**: The Rust CLI only supports positive flags (e.g., `--escape-asterisks`, `--autolinks`, `--wrap`). Negative flags (`--no-*`) are only supported through the Python CLI proxy for v1 compatibility.
#### CommonMark-Compliant List Formatting
[Section titled “CommonMark-Compliant List Formatting”](#commonmark-compliant-list-formatting)
* **Tight lists no longer have blank lines before nested sublists** - This follows the [CommonMark specification](https://spec.commonmark.org/) for list formatting
* Previous behavior (v1): `* Item 1\n\n + Nested\n`
* New behavior (v2): `* Item 1\n + Nested\n`
* **Why**: CommonMark specifies that tight lists (lists without blank lines between items) should not have blank lines before nested sublists
* **Impact**: Generated markdown will render identically in CommonMark-compliant renderers but may look different in source form
* **Migration**: If you need the old behavior for specific platforms, you can post-process the output or use loose lists (with blank lines between items)
### Added
[Section titled “Added”](#added-17)
#### Core Rust Implementation
[Section titled “Core Rust Implementation”](#core-rust-implementation)
* **Complete Rust rewrite** of HTML to Markdown conversion engine using `scraper` and `html5ever`
* **Native Rust CLI** with improved argument parsing and validation
* **PyO3 Python bindings** for seamless Rust/Python integration
* **Automatic hOCR table extraction** with built-in heuristics for OCR documents
#### New V2 API
[Section titled “New V2 API”](#new-v2-api)
* Clean, modern API with dataclass-based configuration
* `convert(html, options, preprocessing)` - primary API entry point
* `ConversionOptions` - comprehensive conversion settings (now includes `encoding`)
* `PreprocessingOptions` - HTML cleaning configuration
* Legacy parsing options removed in favour of explicit encoding on `ConversionOptions`
* Improved type safety with full type stubs (`.pyi` files)
#### V1 Compatibility Layer
[Section titled “V1 Compatibility Layer”](#v1-compatibility-layer)
* **100% backward compatible** v1 API through compatibility layer
* `convert_to_markdown()` function with all v1 kwargs
* Smart translation of v1 options to v2 dataclasses
* CLI argument translation for v1 flags
* Clear error messages for unsupported v1 features
#### Testing & Quality
[Section titled “Testing & Quality”](#testing--quality)
* **77 new tests** for v1 compatibility (32 bindings + 26 CLI + 19 integration)
* Comprehensive integration tests with actual CLI execution
* Wheel testing workflow for cross-platform validation
* Python 3.10, 3.12, 3.14-dev test matrix
* Dual coverage reporting (Python + Rust)
#### CI/CD Improvements
[Section titled “CI/CD Improvements”](#cicd-improvements)
* Shared build-wheels action for consistent wheel building
* Test-wheels workflow with full test suite on built wheels
* Rust coverage with `cargo-llvm-cov`
* Python coverage in LCOV format
* Automated wheel building for Python 3.10-3.13
### Changed
[Section titled “Changed”](#changed-30)
#### Performance
[Section titled “Performance”](#performance)
* **60-80x faster** than v1 for most conversion operations (144-208 MB/s throughput)
* Memory-efficient processing with Rust’s zero-cost abstractions
* Optimized table handling with rowspan/colspan tracking
* Faster list processing with unified helpers
#### Architecture
[Section titled “Architecture”](#architecture)
* Removed Python implementation (`converters.py`, `processing.py`, `preprocessor.py`)
* Migrated to Rust-based conversion engine
* Simplified Python layer to thin wrapper around Rust bindings
* CLI now proxies to native Rust binary with argument translation
#### API Design
[Section titled “API Design”](#api-design)
* More explicit configuration with separate option classes
* Better separation of concerns (conversion/preprocessing/parsing)
* Clearer parameter naming and organization
* Improved error messages and exception handling
### Removed v1 Features
[Section titled “Removed v1 Features”](#removed-v1-features)
The following v1 features were **removed** in v2:
* `code_language_callback` - Removed (use `code_language` option for default language)
* `strip` option - Removed (use preprocessing options instead)
* `convert` option - Removed (all supported tags are converted by default)
* `convert_to_markdown_stream()` - Removed (html5ever does not support streaming parsing)
### Not Yet Implemented
[Section titled “Not Yet Implemented”](#not-yet-implemented)
* `custom_converters` - Planned for future release with Rust and Python callback support
### Migration Guide
[Section titled “Migration Guide”](#migration-guide)
#### For Most Users (No Changes Needed)
[Section titled “For Most Users (No Changes Needed)”](#for-most-users-no-changes-needed)
If you’re using the v1 API, your code will continue to work:
```python
from html_to_markdown import convert_to_markdown
# This still works in v2!
markdown = convert_to_markdown(html, heading_style="atx")
```
#### To Use New V2 API (Recommended)
[Section titled “To Use New V2 API (Recommended)”](#to-use-new-v2-api-recommended)
```python
from html_to_markdown import convert, ConversionOptions
options = ConversionOptions(heading_style="atx")
markdown = convert(html, options)
```
#### CLI Changes
[Section titled “CLI Changes”](#cli-changes)
V1 CLI flags are automatically translated to v2:
```bash
# V1 style (still works)
html-to-markdown --preprocess-html --escape-asterisks input.html
# V2 style (recommended)
html-to-markdown --preprocess input.html # escaping is default
```
### Performance Benchmarks
[Section titled “Performance Benchmarks”](#performance-benchmarks)
Real-world performance improvements over v1 (Apple M4):
| Document Type | Size | V2 Latency | V2 Throughput | Speedup vs V1 (2.5 MB/s) |
| ------------------- | ----- | ---------- | ------------- | ------------------------ |
| Lists (Timeline) | 129KB | 0.62ms | 208 MB/s | **83x** |
| Tables (Countries) | 360KB | 2.02ms | 178 MB/s | **71x** |
| Mixed (Python wiki) | 656KB | 4.56ms | 144 MB/s | **58x** |
V2’s Rust engine delivers **60-80x higher throughput** than V1’s Python/BeautifulSoup implementation across real-world documents.
### Technical Details
[Section titled “Technical Details”](#technical-details-1)
#### Rust Crates Structure
[Section titled “Rust Crates Structure”](#rust-crates-structure)
```text
crates/
├── html-to-markdown/ # Core conversion library
├── html-to-markdown-py/ # Python bindings (PyO3)
└── html-to-markdown-cli/ # Native CLI binary
```
#### Python Package Structure
[Section titled “Python Package Structure”](#python-package-structure)
```text
html_to_markdown/
├── api.py # V2 API
├── options.py # V2 configuration dataclasses
├── v1_compat.py # V1 compatibility layer
├── cli_proxy.py # CLI argument translation
├── _rust.pyi # Rust binding type stubs
└── __init__.py # Public API exports
```
### Breaking Changes Summary
[Section titled “Breaking Changes Summary”](#breaking-changes-summary)
None if using v1 compatibility layer. If migrating to v2 API:
1. **Import changes**: `convert_to_markdown` → `convert`
2. **Configuration**: Kwargs → Dataclasses (`ConversionOptions`)
3. **Defaults changed**: See CommonMark-compliant defaults table above
4. **Removed features**: See [Removed v1 Features](#removed-v1-features) section above
### Complete V1 vs V2 Comparison
[Section titled “Complete V1 vs V2 Comparison”](#complete-v1-vs-v2-comparison)
#### API Differences
[Section titled “API Differences”](#api-differences)
| Aspect | V1 | V2 |
| ----------------------- | ------------------------------- | ------------------------------------------------ |
| **Primary API** | `convert_to_markdown(**kwargs)` | `convert(html, options, preprocessing, parsing)` |
| **Configuration** | Keyword arguments | Dataclasses (`ConversionOptions`, etc.) |
| **Type Safety** | Basic type hints | Full `.pyi` stubs + generics |
| **Compatibility Layer** | N/A | `convert_to_markdown()` with v1 kwargs |
#### Performance Differences
[Section titled “Performance Differences”](#performance-differences)
| Document Type | V1 Throughput | V2 Throughput | Speedup |
| ------------------- | ------------- | ------------- | ------- |
| Lists (Timeline) | 2.5 MB/s | 208 MB/s | **83x** |
| Tables (Countries) | 2.5 MB/s | 178 MB/s | **71x** |
| Mixed (Python wiki) | 2.5 MB/s | 144 MB/s | **58x** |
| Average | 2.5 MB/s | 177 MB/s | **71x** |
#### Implementation Differences
[Section titled “Implementation Differences”](#implementation-differences)
| Component | V1 | V2 |
| ---------------- | --------------------------- | ------------------------- |
| **HTML Parser** | BeautifulSoup4 / lxml | html5ever (Rust) |
| **Sanitizer** | Custom Python | html5ever DOM filtering |
| **Conversion** | Pure Python (\~3,850 lines) | Pure Rust (\~4,800 lines) |
| **Bindings** | N/A | PyO3 |
| **CLI** | Python wrapper | Native Rust binary |
| **Dependencies** | bs4, lxml, soupsieve | None (statically linked) |
#### Output Differences (Default Settings)
[Section titled “Output Differences (Default Settings)”](#output-differences-default-settings)
| HTML | V1 Output | V2 Output |
| ------------------------ | ------------------- | ------------------- |
| `<ul><li>Item</li></ul>` | `* Item` (4 spaces) | `- Item` (2 spaces) |
| `<h1>Title</h1>` | `Title\n=====` | `# Title` |
| `Text*with*stars` | `Text\*with\*stars` | `Text*with*stars` |
| `<br>` | Two trailing spaces | Backslash `\` |
| `<pre>code</pre>` | ` ```\ncode\n``` ` | Indented 4 spaces |
These differences reflect v2’s alignment with CommonMark specification.
### Removed Python Implementation
[Section titled “Removed Python Implementation”](#removed-python-implementation)
* Python implementation of HTML conversion
* `html_to_markdown/converters.py` (1220 lines)
* `html_to_markdown/processing.py` (1195 lines)
* `html_to_markdown/preprocessor.py` (404 lines)
* `html_to_markdown/whitespace.py` (293 lines)
* `html_to_markdown/utils.py` (37 lines)
* Several test files migrated to Rust or marked as `.skip`
Total: **\~3,850 lines** of Python code removed, replaced by **\~4,800 lines** of Rust
### Notes
[Section titled “Notes”](#notes)
* **Platform Support**: Wheels built for Linux, macOS, Windows on x86_64
* **Python Version**: Requires Python 3.10+
* **ABI Compatibility**: Uses `abi3` for Python 3.10+ wheel reuse
* **Rust Version**: Built with stable Rust (tested on 1.75+)
***
## \[1.x] - Previous Versions
[Section titled “\[1.x\] - Previous Versions”](#1x---previous-versions)
For changes in v1.x releases, see git history before the v2 rewrite.
# Changelog archive: 3.16.0–3.14.0
## \[3.16.0] - 2026-10-02
[Section titled “\[3.16.0\] - 2026-10-02”](#3160---2026-10-02)
### Added
[Section titled “Added”](#added)
* **`ConversionOptions::inline_data_media`** chooses what to write for an image or embedded media element whose address is an inline `data:` URL, so the payload no longer has to land in the output. `keep` (the default) writes the URL as before. `alt_text_only` writes the alt text: the title of an inline `<svg>`, the fallback content of `<video>` and `<audio>`, nothing for an `<iframe>`. `drop_element` writes nothing. It covers `<img>`, `<graphic>`, inline `<svg>`, `<video>`, `<audio>` and `<iframe>`. With either of the last two choices, a real address on the element wins over the `data:` one: a lazy-load attribute or `srcset` candidate on `<img>`, another address attribute on `<graphic>`, a nested `<source>` on `<video>` and `<audio>`, and a `<source>` of the `<picture>` that holds an `<img>`. The document structure follows the markdown: no image node for a dropped element, and no address when only the alt text is written. A link whose only content the option removed is dropped with it, instead of turning into a link labelled with its own address. A link whose own address is a `data:` URL gets the same choice: `alt_text_only` and `drop_element` both write the link’s text with no destination, since a link has no caption separate from its text the way an image has alt text, and that text is never dropped along with the address. Extracted images do not change. The CLI takes it as `--inline-data-media` (#528).
### Changed
[Section titled “Changed”](#changed)
* **WASM: assigning `null` or `undefined` to five optional fields now throws.** The fields are `WasmConversionOptions.visitor`, `WasmConversionOptionsUpdate.visitor` and `preprocessing`, `WasmConversionResult.document` and `WasmImageMetadata.dimensions`. They borrow the value you assign instead of taking it, and an assignment of `null` cleared them before. To unset one, call `clearVisitor()`, `clearPreprocessing()`, `clearDocument()` or `clearDimensions()`.
* The `alef` pin in `alef.toml` is now 0.101.0, the version that generated the committed bindings. Regenerating with 0.97.0 dropped the Go binding’s `runtime.LockOSThread` calls.
* The FFI Symbols CI gate now fails when a detector matches no call site, and names the silent language. Before, a detector that stopped matching read exactly like a clean pass, so a restyled binding dropped out of the diff with every check green. Each detector must also match in every one of its required roots: the binding package for C#, Java, Go and Zig, and both `e2e/c` and `test_apps/c` for C. So the alef-generated `e2e/zig` tests cannot keep a silent Zig binding looking covered, and the vendored Go copy of the C header cannot do the same for C. The PHP comparison fails the same way once the extension exports a function and its probe root is missing. The `--json` summary now carries the per-language counts, the per-root counts and the silent detectors.
* CI E2E now ends in one `E2E result` job that fails unless every other job in the workflow passed or was skipped because its path filters did not match. Before, a skipped leg left the run as green as a passing one, whatever the reason for the skip, and no single check covered every leg. Each leg’s path filter condition is now written once, as an output of the change detection job, and both the leg and the result job read that output. A script test fails when a job is added to the workflow without being listed in the result job.
* Removed an unused copy of the `<a>` handler that no conversion path called. Links are converted by the one live handler, as before; output does not change.
### Fixed
[Section titled “Fixed”](#fixed)
* **Text after a `<center>`, `<search>`, `<hgroup>` or `<dialog>` in a table cell joined it (#692).** `<table><tr><td>a<center><h2>h</h2>x</center>y</td></tr></table>` gave `| a h xy |` in both converters, and the full converter wrote `| a h x y |` for a `<dialog>`. These convert like a `<div>` but were not counted as blocks, so the text after them got no cell break. They now give `| a h x y |`, or `| a<br>h<br>x<br>y |` with `br_in_tables` on, as a `<div>` does. In a list item, text after one of them now starts a paragraph in the item, as after a `<div>`, instead of continuing the container’s last line or leaving the list. Counting them as blocks changes three more outputs, again to match a `<div>`. With `newline_style: backslash`, the hard break before one of them is dropped: `<p>a<br><center>b</center>c</p>` gives `a`, `b` and `c` as paragraphs instead of `a\` then `b`. A dialog in a link label is set off by spaces, so `<a href="u">l<dialog>b</dialog>m</a>` gives `[l b m](u)` instead of `[lb m](u)`. Bold or italic around one of them is closed before it and opened again after it: `<p><b>a<center>b</center>c</b></p>` gives `**a**`, `**b**` and `**c**` instead of one bold run across three paragraphs. Visitors now get `is_inline` false for these four tags.
* **Text before a `<dialog>` ran into it (#692).** `<p>a<dialog>b</dialog>c</p>` gave `ab`, then `c`, and `<td>a<dialog>b</dialog>c</td>` gave `| ab c |` in the full converter and `| a bc |` in the fast one: the dialog wrote no break before its content. A dialog now converts like a `<div>`, so the paragraph gives `a`, `b` and `c` as three paragraphs, the cell gives `| a b c |` in both converters, and in a list item the dialog content starts a paragraph in the item.
* **Plain text output joined a `<center>` or `<dialog>` to the text after it (#692).** `<p><b>a<center>b</center>c</b></p>` with `output_format: plain` gave `abc` on one line. Plain output now starts both on their own line, as it does for a `<div>`: `a`, `b` and `c`.
* **A `<details>`, `<summary>`, `<menu>` or `<legend>` joined the text around it (#692).** In a table cell, `<td>a<menu>b</menu>c</td>` gave `| ab c |` and a summary gave `| a**b** c |`. In a list item, the text after a details left the list, and a summary, menu or legend ran into the text before it. In a paragraph, `<p>a<summary>b</summary>c</p>` gave `a**b**`, then `c`. A details and a menu now convert like a `<div>`, and a summary or legend is placed the way a `<div>` is placed and stays bold: the cell gives `| a b c |` or `| a **b** c |` in both converters, the list item keeps `b` and `c` as paragraphs in the item, and the paragraph gives `a`, `b` and `c` apart. As with the tags above, these four now count as blocks: the backslash break before them is dropped, bold around a details, summary or menu is closed and reopened, plain output starts a menu or legend on its own line, and visitors get `is_inline` false for them. A summary that holds a list with a quote in it, inside a details in a list item, now stays in the item, so with the default or tab list indent its bold markers no longer span the quote.
* **A block in a heading ran into the words around it.** `<h1>a<div>b</div>c</h1>` gave `# abc` in the full converter and `# a b c` in the fast one. Both now give `# a b c`, for a `<div>` and for every tag that converts like one, a details and a menu included. In the fast converter, a block inside a summary, figcaption or table caption now writes its break into that element’s text, so a rustdoc heading such as `impl Any for T<div class="where">where T: ...</div>` gives `for T where` instead of `for Twhere`.
* **In a heading in a table cell, the text after a block ran into it.** `<td><h2>a<div>b</div>c</h2></td>` gave `| a bc |`. The text after the block now gets the cell break, so the cell gives `| a b c |`, or `| a<br>b<br>c |` with `br_in_tables` on. The fast converter leaves this shape to the full converter.
* **In a link label in a table cell, the text after a block ran into it.** `<td><a href="u"><span>a<div>b</div>c</span></a></td>` gave `| [a bc](u) |`. The text after the block now gets the cell break, as in a heading in a cell, so the cell gives `| [a b c](u) |`, or `| [a<br>b<br>c](u) |` with `br_in_tables` on.
* **Plain text output left a list item marker alone on its line.** `<ol><li><div>a</div>b</li></ol>` with `output_format: plain` gave `1.` on a line of its own, then `a` and `b`. A block that opens a list item now starts on the marker line, so the item gives `1. a`, then `b`.
* **The fast converter dropped the bold of a `<legend>` and split a link label at a `<summary>`.** `<legend>x</legend>` gave `x` where the full converter gives `**x**`, and `<a href="u">l<summary>b</summary>m</a>` gave a link label across three paragraphs where the full converter gives `[l b m](u)`. The fast converter now writes a legend in bold, as it does a summary, and leaves a summary inside a link to the full converter, as it already did for a `<div>`.
* **The WASM binding used up a visitor handle on assignment, and `convert()` ignored `options.visitor` (#517).** Assigning a `WasmVisitorHandle` to `WasmConversionOptions.visitor` moved it into the options, so a second options object could not take the same handle. The setter now borrows the handle. `convert()` now uses `options.visitor` when you pass no visitor argument, and a visitor argument still wins over the options field.
* **A line break on its own source line became a paragraph break (#683).** `First\n<br>\nSecond` gave `First\n\nSecond`, two paragraphs: the newline before the `<br>` put its hard-break marker on a line of its own, and an empty line ends a paragraph. The break now ends the line of the text before it, `First \nSecond`, in both converters and with both newline styles. This also holds when that text ends inside an element that writes no line end, such as `<span>`, `<font>` or a custom element: `<span>First\n</span><br>Second`.
* **A table cell ignored `escape_underscores` and `escape_asterisks` (#638).** The full converter always escaped `_` and `*` in a cell, so `<table><tr><td>sample_value</td></tr></table>` gave `sample\_value` while `<p>sample_value</p>` gave `sample_value`. Every escape option now acts the same in a cell as anywhere else. A `|` in a cell is still escaped whatever the options say, and with `escape_ascii` on and `escape_misc` off it is now escaped once, as `\|`, instead of as `\\|`, which some renderers show with a stray backslash.
* **A `|` in a code span, link or image in a table cell broke the table.** `<table><tr><td><code>a|b</code></td></tr></table>` gave ``| `a|b` |``. GFM splits a row on a pipe in a code span too, so the row no longer matched the delimiter row and the whole table became a paragraph. A pipe in a link destination or title, an image description, preformatted text or a code span in a nested table did the same. In Markdown output every pipe in a cell is now escaped as `\|`, which GFM reads as `|` in a code span too. In Djot output a pipe in a link or an image in a cell is now escaped as `\|`, and a pipe in a verbatim span stays bare, because Djot does not split a row there.
* **An empty task item lost its checkbox on GitHub.** `<ul><li><input type="checkbox"></li></ul>` gave `- [ ]`. GFM reads a checkbox only when content follows it, so cmark-gfm and markdown-it showed the text `[ ]`. It now gives `- [ ] `, a checkbox: the character reference renders as a space. Djot output does not change.
* **Text next to a paragraph, heading or other block in a table cell joined it (#645).** `<table><tr><td><p>a</p>b</td></tr></table>` gave `| ab |`, and so did a heading, a `<div>`, a list or a code block before the text. Text before a heading or a code block joined it too. A block in a cell is now separated from the cell content before and after it by the cell break: `| a b |`, or `| a<br>b |` with `br_in_tables` on. A block at the start of bold, a code span or another inline element still joins the text before that element, and a block inside a heading still joins the text next to it.
* **The two converters wrote a quote or a paragraph in a table cell differently (#647).** A quote in a cell now has no `>` marker in either converter, as a heading, a list and a code block in a cell have none: `<blockquote>a</blockquote>b` gives `| a b |`. The fast converter wrote a paragraph after other cell content as `<br>` with `br_in_tables` off; it now writes a space, as the full converter does.
* **The fast converter dropped a line break that no element encloses (#679).** `a<br>1) t` gave `a1) t`, so the two lines joined. The fast converter now writes the break as the full converter does, `a \n1\) t`, the same as when the input sits in `<body>`. The line after a hard break also no longer keeps a leading space: `<div>a<br> b</div>` gives `a \nb` in both converters.
* **Hard breaks that differed between the converters or lost their place.** A whitespace character reference after a break (`a<br>
b`) no longer makes a paragraph break in the fast converter. A break in a heading followed by a space gives one space (`## a b`). With the backslash newline style, a line in a list item that holds only a break keeps the item’s indent (#681). Wrap no longer cuts a list item’s text at a `===` line left of the item’s column, which dropped the hard breaks after it (#680), and keeps a hard break right before such a line.
* **Two ordered lists next to each other became one list (#666).** `<ol><li>a</li></ol><ol><li>b</li></ol>` gave `1. a\n\n1. b`, which CommonMark and Djot read as one list, because a blank line does not end a list. An ordered list that follows an ordered list with only blank lines between them now writes the other delimiter, so it gives `1. a\n\n1) b`, also when a section, article, figure or similar element wraps either list. A list written as text, in a heading or between inline markers, keeps `.`.
* **In Djot output a nested list directly under its item’s text was text (#670).** Djot needs a blank line before a list that follows text, so `- a\n * b` is one paragraph there. A nested list after its item’s text now starts after a blank line in Djot output: `- a\n\n * b`.
* **An empty nested list item after text turned the text into a heading (#667).** `<ol><li>a<ul><li></li></ul></li></ol>` gave `1. a\n -\n`: an empty item cannot interrupt a paragraph, so the lone `-` read as a heading underline and the item was lost. A nested list whose first item writes nothing on its marker line now starts after a blank line: `1. a\n\n -\n`. An empty item after text directly inside its list does the same: `<ul>t<li></li></ul>` gives `t\n\n-\n`, not `t\n-\n`. A list between inline markers, such as a highlight, is text and does not change. With custom `bullets` such as `-`, nested single-item lists that end in an empty item wrote `- - -`, a thematic break. The empty item’s marker now starts the next line, at the column it had on the line of markers: `- -\n -`.
* **A task item in an ordered list lost its number (#659).** `<ol><li><input type="checkbox">p</li></ol>` gave `- [ ] p`, a bullet list. A task item now writes the marker of its own list, so it gives `1. [ ] p`, and its content column follows the width of that number. Djot output keeps `- [ ] p`, because Djot has task items only in bullet lists.
* **A nested ordered list that does not start at 1 joined the text before it (#662).** CommonMark lets only a list that starts at 1 interrupt a paragraph, so in `<ol start="10"><li>a<ol start="100"><li>q</li></ol></li></ol>` the line `100. q` was part of the paragraph `a`. Such a list now starts after a blank line when a paragraph is open before it: `10. a\n\n 100. q`. The blank line makes the outer list loose.
* **Text after a line break became a list, quote or heading (#651).** `<p>a<br>1) t</p>` gave `a \n1) t`, so `1) t` became a list item; in bold, in a list item, in a quote and at the top level alike. Text that starts the line after a hard break and would interrupt the paragraph (`1.`, `1)`, `01.`, `-`, `+`, `*`, `>`, `#`, a rule, a fence or an underline) now has that character escaped, `1\) t`, in both converters. A line that cannot interrupt a paragraph, like `2. t`, is left as it is.
* **Heading text that reads as a closing `#` or a link definition lost the heading (#661).** `<h1>#</h1>` gave `# #`, an empty heading, because CommonMark reads a `#` run at the end of the line as the heading’s closing sequence; `a #` and `##` lost their `#` the same way. Such a run now has its first `#` escaped, `# \#`, in both converters. With `heading_style: underlined`, `<h1>[a]: b</h1>` gave `[a]: b` over its underline, which is a link reference definition, so the heading was lost. Text that starts a definition now has its `[` escaped, `\[a]: b`. A Djot heading and a closed ATX heading keep their `#` run as it is, and plain heading text is unchanged.
* **A table that starts a task item became the task’s text (#630).** `<ul><li><input type="checkbox"><table><tr><td>c</td></tr></table></li></ul>` gave `- [ ] | c |`, so the header row was the task’s text and the table was lost. A table that is a task item’s first content now starts after a blank line at the content column, also inside a `<div>` or `<section>`. A block in an element that writes nothing before it, like a `<span>` or an `<hgroup>`, now also starts below the checkbox; in bold or a link it stays text on the checkbox line.
* **The fast converter dropped a task item’s checkbox (#632).** With the fast converter forced, `<ul><li><input type="checkbox"><p>p</p></li></ul>` gave `- p`. A list item that holds a checkbox now goes to the full converter, which writes `- [ ] p`. The full converter also reads `type="CHECKBOX"` as a checkbox now, as a browser does.
* **Content after an HTML block that `preserve_tags` keeps joined the block (#655).** CommonMark ends an HTML block only at a blank line, and none followed a preserved block element, so in `<ul><li><input type="checkbox"><div></div><h2>h</h2>t</li></ul>` the heading and the text were part of the HTML. A blank line now follows a preserved element that starts an HTML block, in a list item and at the top level: `- [ ] \n <div></div>\n\n ## h\n t`.
* **A table whose cells held only rules was dropped (#628).** The full converter took a table with no text and no image for a blank spacer table and wrote nothing, so `<table><tr><td><ul><li><hr></li></ul></td></tr></table>` gave an empty document. A rule now counts as content, and both converters write the table as `| --- |` over its delimiter row. Text in a cell that looks like a list marker no longer turns a rule after it into `___`, and the fast converter now trims the space before a rule in a cell as the full converter does.
* **A table whose only cell held a line break was dropped with `br_in_tables` on (#646).** `<table><tr><td><br></td></tr></table>` gave an empty document from the full converter while the fast converter kept the table as `| <br> |`. With `br_in_tables` on, a `<br>` in a cell writes a literal `<br>`, so it now counts as content, matching the fast converter; with the option off it still collapses to a space the cell trims away, so the table is still dropped there, as it was before.
* **A rule inside bold, italic, a summary or a caption split the emphasis markers (#603).** The rule was written after a blank line, which ended the paragraph between the markers, so the markers showed as literal text: `<summary>t<hr></summary>` gave `**t\n\n---**`, and a definition list that starts its definition with a rule did the same inside a caption, `<b>` or `<em>`. Markdown has no rule inside emphasis, so the rule is now the text `---` in the running line, as it already was in a link: `**t ---**`. This covers `<b>`, `<strong>`, `<em>`, `<i>`, `<summary>`, `<figcaption>`, a table caption, `<del>`, `<s>`, `<strike>`, `<ins>`, `<mark>`, `<var>`, `<dfn>`, `<q>`, and `<sub>` and `<sup>` when they write a symbol.
* **A list item took the checkbox of an item in its nested list (#604).** `<ul><li>X<ul><li><input type="checkbox" checked> A</li></ul>ZZ</li></ul>` gave `- [x] X AZZ`: the outer item became a task item and the nested list was joined into its text. A checkbox in a nested list now belongs to that list’s item, so the output is `- X`, the nested `- [x] A` and then `ZZ`.
* **Text after a quote, in a list inside bold, italic or `<q>`, rendered inside the quote (#615).** `<b><ul><li>x<blockquote>q</blockquote>t</li></ul></b>` gave `**- x\n > q\n t**`, so `t**` continued the quote’s paragraph. The first item’s marker follows the opening marker, so that item is text and writes no content column, and the blank line after the quote went with the column. A nested item’s marker starts its own line, so it is a real list item, and `**- a\n * x\n > q\n t**` kept `t` in the quote too. Text after a quote or a nested list now starts after a blank line, at the column of the innermost real list item: `**- x\n > q\n\nt**` and `**- a\n * x\n > q\n\n t**`. A quote 4 or more columns past that item’s column, or past the start of the line when no item is real, is the paragraph’s own text, so nothing changes there and the markers stay in one paragraph.
* **A quote that starts a list item rendered outside the item (#617).** `<ul><li><blockquote>q</blockquote></li></ul>` gave `-\n> q`, an empty item and a quote after the list, also when the list is inside a quote. The quote now starts on the marker line, `- > q`.
* **A quote that starts a task item became the task’s text (#622).** A checked task item whose first content is `<blockquote>q</blockquote>` gave `- [x] > q`, which renders the text `[x] > q`. The quote now starts on the next line at the item’s content column, `- [x] \n > q`. The checkbox line ends in a space written as a character reference: GFM reads a checkbox only when content follows it, so cmark-gfm shows a bare `[x]` line as text. A nested list, a heading or a code block that starts a task item does the same, also inside a `<div>` or a `<section>`, and also when the checkbox is in a `<p>` of its own. A rule there gave `- [ ] ---`, the text `[ ] ---`; it now comes after a blank line, `- [ ] \n\n ---`, since `---` right under the checkbox line makes that line a heading.
* **A rule that starts a list item rendered outside the item (#623).** `<ul><li><hr></li></ul>` gave `-\n\n---`, an empty item and a rule after the list. The rule is now `___` on the marker line, `- ___`: `- ---` is a rule of its own.
* **Text inside a list before an item joined the item’s marker (#625).** `<ul>how<li>do</li></ul>` gave `how- do`, one line of text, and the item was lost. The item now starts its own line, `how\n- do`. When its marker cannot interrupt the text above it, as with `3.`, a blank line comes first: `how\n\n3. do`.
* **Text after a quote stayed in the quote for a later item of a list inside bold or italic (#633).** `<b><ul><li>a<ol><li>x</li><li>y<blockquote>q</blockquote>t</li></ol></li></ul></b>` gave `**- a\n 1. x\n 2. y\n > q\n t**`, and `t**` continued the quote. The marker `2.` cannot interrupt a paragraph, but after the real item `1. x` no paragraph is open, so `2.` starts an item. The same holds after a quote of the enclosing item. Text after the quote now starts after a blank line: `**- a\n 1. x\n 2. y\n > q\n\n t**`.
* **Some first blocks of a task item still became the task’s text (#634).** An ordered list that starts at a number other than 1 and a code block in the indented style cannot interrupt the checkbox line, so they now start after a blank line: `- [ ] \n\n 3. x` and `- [ ] \n\n c`. The code block keeps its indent; before, `- [ ]\n c` lost the code. A quote after an empty inline element, such as `<span></span>`, now starts on the next line like a quote right after the checkbox. An image before the quote is still text on the checkbox line, and so is an empty element that `preserve_tags` writes as HTML. An empty list, heading or code block writes nothing, so text after it stays on the checkbox line: `- [ ] t`. A fenced code block that holds only whitespace still writes its fences, so it starts on the next line and the text after it stays out of the code.
* **A quote after a line break in a task item stayed on the checkbox line (#650).** `<ul><li><input type="checkbox"><br><blockquote>q</blockquote></li></ul>` gave `- [ ] > q`, and the quote was text. The converter’s own output now decides which element writes first, also inside a `<div>` or a `<section>`. A line break, a ` `, a `<template>`, a `<noscript>`, an `<input>` that is not the checkbox, an empty `<picture>` or an image with `skip_images` writes nothing there, so the quote now starts on the next line: `- [ ] \n > q`.
* **An underlined heading ended its list item (#635).** With `heading_style` set to `underlined`, the underline of a heading in a list item was written at column 0: `<ul><li><h2>q</h2></li></ul>` gave `- q\n-`, an item and an empty item. The underline now gets the item’s content column, `- q\n --`. After a line of the item, the heading starts after a blank line, so it does not continue that line’s paragraph: `- a\n\n q\n --`. A block after a heading of one letter starts its own paragraph: `<ul><li><h2>q</h2><p>t</p></li></ul>` gives `- q\n --\n\n t`. In a list item the underline has at least two dashes, since a lone `-` line reads as an empty item.
* **Many blocks in one list item took quadratic time (#649).** Each block checked every earlier line of the item to see whether the item was still open, and each item of a list inside bold or italic checked every earlier item. `<ul><li>` with 5000 headings after text took seconds. Each check now reads only the lines written since the last one, so the time grows linearly.
* **A heading after text in a quote joined the text (#640).** `<blockquote>a<h2>q</h2></blockquote>` gave `> a## q`, a paragraph, and with `heading_style` set to `underlined` it gave `> aq\n> -`, one heading. The heading now starts after a blank quote line: `> a\n>\n> ## q`. An underlined heading does the same after any line of text in the quote, such as a line that ends in a hard break or the last item of a list.
* **An underlined heading whose text starts a block lost its heading (#653).** With `heading_style` set to `underlined`, `<h2>-</h2>` gave `-\n-`, two empty list items. The text of an underlined heading is now escaped where it would start a block: a list marker (`-`, `*`, `1.`, also on its own), a quote, a `#` heading or a rule. `<h2>-</h2>` gives `\-\n-`.
* **The lines of a list item in a quote or under tab indent left the item (#654).** A list inside a quote in a list item counted the markers outside the quote too, so its lines sat further in than the item, and the underline of a heading sat short of it. The quote now starts its content as a container of its own, so a list in it counts only its own markers. A block after text in a list item inside a quote now also starts its own line, as it does outside a quote. An underlined heading in a quote in a list item now gets the one-dash underline it gets in a quote elsewhere: `<ul><li><blockquote><h2>q</h2></blockquote></li></ul>` gives `- > q\n > -`, where it gave `- > q\n > --`. Bold or italic around the quote no longer changes the lists in it, so text after a nested quote in such a list leaves the nested quote. With `list_indent_type` set to `tabs`, the lines of a nested item were one tab short of its content column: `- a\n\t* q\n\n\tt` put `t` in the outer item. They now reach the column where the item’s text starts, `- a\n\t* q\n\n\t\tt`. With `list_indent_width` set to 4 or with tab indent, a quote right after an opening bold marker, a summary’s or a caption’s, now writes a nested quote or list of its list at the column of the nearest real list item, where they became a code block. A list inside `<mark>` or `<del>` is now text after its marker, as inside bold, so text after a quote in it no longer becomes a code block.
* **Wrap mode joined a rule or a heading underline to the text next to it (#607).** With `wrap` on, a `---` line followed by text became one line of text, `--- B`, and the rule was lost. The underline of an underlined heading was joined to the heading text (`Heading -------`), or cut off from it by a blank line for `=======`, so the heading was lost too. A rule now stays on its own line, and an underline stays right under its heading text, which is not reflowed, as with a `#` heading. Both hold inside a quote too.
* **Wrap mode joined the keys of the frontmatter into one line.** With `wrap` on and metadata extraction on, the YAML frontmatter went through the reflow like body text, so `---\ntitle: My Page\n---` became `--- title: My Page ---` and the frontmatter was lost. Only the text after the frontmatter is wrapped now.
* **Wrap mode folded list items, code fences, headings and table rows inside a quote into text.** With `wrap` on, `<blockquote><ul><li>alpha</li><li>beta</li></ul></blockquote>` gave `> - alpha - beta`, one item, and a code block inside a quote lost its code. Outside a quote, a `~~~` code block was reflowed like a paragraph. Every line that starts a block now keeps its own line in and out of a quote, and a code block ends only at a fence that closes it.
* **Wrap mode turned a tight list loose when an item went on to a second line (#616).** A line right under a list item that starts no block of its own, at column 0 or indented, belongs to the item’s text. With `wrap` on, the reflow wrote it as a paragraph of its own and put a blank line before the next item, so the list rendered loose. It now joins the item’s text and is wrapped with it. For the same reason, a line that starts with a number such as `1990.` or `57)` stays in its paragraph, in a quote and in a list item: only a bullet or a number equal to 1, such as `1.` or `01)`, can end a paragraph and start a list. Under a list item, a number line left of the item’s text still ends the item.
* **Wrap mode dropped a hard line break (#613).** With `wrap` on, `<p>a<br>b</p>` gave `a b`: the reflow joined the line after a `<br>` to the line before it, in a paragraph, a quote and a list item. A hard break is now a line end the reflow never joins across, so each side of it is wrapped on its own and the break stays, with both newline styles.
* **Wrap mode could start a line with a list marker and turn text into a list (#614).** With `wrap` on, a break before a `-`, `1.`, `#` or `>` in running text started a new line with it, which opened a list, a heading or a quote. A wrapped line now never starts with a word that opens a block there, also in a run such as `--- --- ---` or `* * *`; the word stays at the end of the line before it, which can then run past the wrap width. A number equal to 1 with leading zeros, such as `01.` or `001)`, opens a list like `1.` does, so it is kept off a line start too, and a link label or image alt line that starts with one is escaped. A number followed by non-breaking spaces, such as Word’s `1. Cut`, is no longer read as a list marker, and the reflow no longer breaks a line at a non-breaking space.
* **Wrap mode broke a link whose address holds a space.** An address with a space is written in angle brackets, `[Share](<https://example.com/?text=a b>)`, and a line end inside the brackets ends the link. With `wrap` on, the reflow broke the line there. It now keeps the address in angle brackets on one line.
* **Wrap mode cut a nested list marker off from its text.** A list item that holds a nested list on its own line, such as `- 3. [vote](...) title`, wrapped to `- 3.` and the text on the next line. `- 3.` alone is an empty nested item, and the text below it left the nested list. The reflow now treats both markers as one, so the text stays in the nested item. An item whose text starts a heading or a code fence, such as `- ## Title`, is no longer reflowed: the heading kept only its first words, and the code lines were joined and wrapped like text.
* **A page whose bytes open with a mangled byte order mark lost its whole head.** A real leading U+FEFF is stripped before parsing, but one a wrong encoding guess mangles beyond recognition reads as ordinary text by the time #527’s head search sees it, and that search treated any such text as the start of the body, so it gave up before it ever reached `<head>` and reported no title, no meta tags and no base or canonical link. A browser discards anything ahead of the document’s own `<html>` tag without letting it block the real head inside, so the head search now does the same: text directly in front of `<html>` no longer ends the search, on both tiers. A head-only fragment with no `<html>` tag is unaffected: text ahead of `<head>` there still ends the search, as #527 intended.
* **An `<img>` whose `src` spelled the `data:` scheme in upper or mixed case ignored its lazy-load address.** The check that sends a `data:` source to the `data-src`, `data-lazy-src`, `data-original` and `srcset` fallbacks compared the scheme in lower case only, so `<img src="DATA:..." data-src="real.png">` kept the payload while the same image with `data:` used `real.png`. The scheme now matches in any case.
* **An image whose `data:` scheme was written in upper or mixed case was not extracted, and the metadata reported it as a relative image.** Inline image extraction and the metadata image type compared the scheme in lower case only. Every check now uses the one case-insensitive test the converter uses for its markdown output.
* **Text right after a list or a table rendered inside it (#570, #571).** Inline content that directly followed a list or a table in the same container continued the block’s last line. After a list it became a lazy continuation of the last item, so `<div><ul><li>A</li></ul>para</div>` rendered `para` inside the item; after a table it became one more table row. Inline content after a block now starts its own paragraph after a blank line, the same as text after a paragraph, in both rendering paths. This includes a list item that ends in a line break, and a `<br>` right after a list with backslash line breaks, which also put the text inside the item. Text after a horizontal rule gets the same blank line.
* **A block inside a list item, and the text after it, left the item (#583).** A heading after the item’s text joined that text (`<li>A<h3>H</h3>tail</li>` gave `- A### H`), a rule ended the list, and the text after a div, table, blockquote, nested list or definition list became a lazy continuation of that block. The text after a code block or paragraph, a definition list, and a section, article, header, footer, aside or main element fell out of the list. Inside a list item, a block after other content of the item now starts on its own line at the item’s content column, and text after a block starts its own paragraph at that column. A paragraph or div after the item’s text is now its own paragraph instead of joining the text, which makes the list loose. The column is written only while the item is still open, also inside a definition list or a section that the item holds. Whitespace between the marker and the item’s first block no longer counts as content in strict whitespace mode, and with `wrap` a paragraph inside an item keeps its indent, also inside a blockquote. The fast conversion path hands these items to the full converter.
* **Text after a list or table at the end of an inline wrapper continued it (#585).** In `<div><span><ul><li>A</li></ul></span>para</div>`, `para` still continued the list’s last item, because the rule from #570 looked only at the element right before the text. Text after an inline element whose last content is a block now starts its own paragraph too, in both rendering paths.
* **A horizontal rule right after a line of text turned the text into a heading (#584).** Inside a paragraph, and at the start of a definition, the rule was written on the line right after the text, so `<p>t<hr>B</p>` gave `t\n---` and `<dl><dt>t</dt><dd><hr></dd></dl>` gave the same. Markdown reads `---` under text as a heading underline, so `t` became a heading and the rule was lost. The rule now starts after a blank line there too, as it already did after text in a `<div>`.
* **The nightly benchmark guardrail scored timings on hardware it was never calibrated on.** The runner pool moved from the AMD EPYC 9V74 the baseline was calibrated on to an EPYC 7763, and every fixture read 15% to 45% slower. `htmbench compare` still scored each timing, printed 26 `FAIL` lines, and then passed the run as advisory, so the job was green while measuring nothing. On a CPU other than the calibrated one no timing is scored now: the run reports `TIMINGS NOT SCORED` with both CPUs and fails, and under `--allow-host-mismatch` (the nightly job) it succeeds with a `Benchmark timings not scored` warning on the run page instead. The fixture inventory stays fatal on any host, and a regression on the calibrated CPU still fails.
* **The benchmark baseline recorded stale output sizes for five fixtures.** The 3.14.2 conversion fixes moved the Markdown output of `gh-121-hacker-news`, `gh-127-issue`, `gh-190/firsteigen`, `gh-190/rbloggers` and `wikipedia/small_html`, and the baseline was never updated. Each change was traced to the fix that made it and reviewed: images kept in layout rows (5b26d732d, 31f2015b1), and whitespace no longer opening a line (c5b8d1baa), which also stops two lines rendering as indented code blocks. Only `output_bytes` changes; the calibrated timings stay as measured. `gh-190/plusblog` changed for a different reason, fixed below.
* **An `<img>` with no usable `src` could take its address from the middle of a `srcset` candidate.** The fallback split `srcset` and `data-srcset` on every comma, so a comma inside a parenthesised descriptor or inside a URL started a new candidate: `a.png (x, b.png 3x ), c.png 2x` produced `b.png`, and `a.png?w=1,2 2x` produced `2`. Candidates are now split with the HTML spec’s srcset parsing steps, including the parentheses rule, and only the spec’s five ASCII whitespace characters separate a URL from its descriptor.
* **The `srcset` fallback could choose a candidate a browser never loads, or compare a width with a density.** Descriptors were read with Rust’s float parsing and nothing else, so `a.png foo` stayed eligible, `a.png infx` beat every other candidate, a first `NaNx` candidate could not be beaten, `+2x` counted as `2x`, and `900x` beat `800w`. Descriptors now go through the spec’s descriptor parser: a candidate with an unknown token, a number outside the spec’s grammar, a zero width, a second descriptor of one kind, or an `h` without a `w` is dropped, and a list with no valid candidate keeps `src`. Widths and densities are not compared with each other, because a browser needs `sizes` and the viewport to do that: when any candidate has a width, the largest width wins, and otherwise the largest density wins, a candidate with no descriptor counting as `1x`.
* **A `<br>` in a `<span>` after a list or a layout table pulled the next paragraph into the last list item.** A `<span>` removed the line break that ends the item’s line, so the `<br>` became a hard break at the end of the item and the paragraph after it rendered inside the item. Without a `<br>`, the span’s text was joined onto the item’s last word, and a `<span>` right after a horizontal rule was joined onto the `---`. A `<span>` now leaves the line break before it in place (#546).
* **Head metadata kept its character references encoded.** The `<base href>`, the `<link rel="canonical">` href and the `<title>` text reached the frontmatter and the structured metadata as written, so `<base href="https://example.com/it's/">` produced `base: https://example.com/it's/`. They now go through the same decoder as `<meta content>` and body text, including the Windows-1252 mapping for numeric references 128-159.
* **A newline in a head value started a new frontmatter key.** The frontmatter wrote each `key: value` line as it was, so a `<title>` or `<meta content>` holding a newline, literal or written as `
`, could add or override a key. Each key and value is now one YAML scalar: a value that plain YAML would misread (a newline, `: `, a space before `#`, a leading `-`, `#` or `@`, a control character) is written in double quotes with YAML escapes. Other values stay unquoted.
* **Legacy named references without a semicolon were not decoded.** The spec lets about a hundred names such as `©`, `&` and `é` close without `;`, and browsers decode them in text: `© 2024` is `© 2024`. The converter kept them as written. They now decode on both tiers, with the spec’s longest-name rule (`¬it;` is `¬it;`). In an attribute value a legacy name followed by `=` or a letter or digit stays as written, so `?a=1©=2` in an `href` is unchanged.
* **Frontmatter values that YAML reads as numbers, booleans, null or dates were not quoted.** A value such as `3`, `true`, `null` or `2024-01-01` is a valid plain scalar, so a YAML reader turned `meta-algolia-search-order: 3` into the number 3. A value that the YAML 1.2 core schema or a YAML 1.1 reader resolves to anything other than a string is now written in double quotes.
* **Numeric character references without a semicolon were not decoded.** The spec decodes `'` and `'` without their `;`, in text and in attribute values, so `it's` is `it's` in a browser. The converter kept the reference as written. It now decodes on both tiers.
* **Tier 1 kept a reference encoded after an unknown name.** When an unknown name such as `&foo` had a `;` a few bytes later, Tier 1 wrote the whole span as it was, so `&foo &` kept `&` where Tier 2 wrote `&`. Tier 1 now writes the `&` alone and reads on, as Tier 2 does.
* **Tier 1’s fallback message added a `;` the page did not have.** When Tier 1 handed a reference without its `;` to Tier 2, the log message showed `'` for an input of `'`. The message now shows the reference as written (#565).
* **Tier 1’s fallback message called a known reference unknown.** When Tier 1 handed a reference without its `;` to Tier 2, the log message called it an unknown HTML entity even when the reference was one Tier 2’s decoder knows, such as `'` or `©`. The message now says the reference is missing its `;` when the name is known, and keeps the unknown wording for names that really are unknown (#586).
* **`base_url` could pick a `<base href>` that a browser ignores.** The document base came from a byte scan for the first `<base` tag in the source, so a `<base>` inside a comment, inside `<title>`, `<textarea>`, `<script>`, `<style>` or another raw-text element, inside `<template>` or SVG, or in a body that a `<frameset>` replaces, set the base for every relative link. The base now comes from the first `<base>` with an `href` in tree order, read from an html5ever parse of the document. The parse stops at the first `<base href>` once no later markup can place a node in front of it or remove it, in `<head>` or in the body, and a page without a `<base` tag is not parsed at all. Found while adopting `base_url` downstream, where the same two mistakes had already been fixed once in a link pre-pass.
* **A `data:` or `javascript:` `<base href>` became the base for relative links.** A browser ignores such a base and resolves against the page’s own URL, as the HTML “frozen base URL” steps require. `base_url` now does the same, so relative links on such a page resolve against the caller’s `base_url` instead of failing to resolve.
* **The `base` and `canonical` metadata kept the last tag, not the first.** The head extractor overwrote each value when it met another tag, so the reported `base` could differ from the base that `base_url` resolves against. The `base` metadata (and `base_href` in the document metadata) is now the same first `<base href>` in tree order that the document base uses, read once, and the first `<link rel="canonical">` wins.
* **The `<meta>` metadata kept the last tag with a given name.** Each `<meta name>` or `<meta property>` overwrote the value an earlier tag with the same key had stored. The first tag per key now wins on both tiers, as the `base` and `canonical` metadata do.
* **A page without a `<head>` tag reported no `base` metadata.** The parser creates the head itself, so `<base href="https://a.example/"><p>x</p>` sets the document base, but the head extractor looked for a `<head>` tag in the source and found none. The `base` metadata now comes from the same parsed document as the document base on both tiers, with or without a `<head>` tag.
* **A `>` inside a `<base>` attribute value turned off the early stop of the base parse.** The parse is fed in pieces, and a piece could end inside the quoted value, so the `<base>` tag only completed in the next piece, which was never checked. The parse now notes each `<base href>` element when html5ever’s tree builder creates it and checks only that element’s ancestors, so the parse stops wherever the tag bytes fall, and the cost of the check does not grow with the size of the tree. The document base itself was always correct.
* **The `title` metadata kept the last `<title>`, not the first.** A head with the titles First and Second reported Second, while a browser shows First. The first title now wins on both tiers, as the `base`, `canonical` and `<meta>` metadata already do. An empty first title also wins, as in a browser, so the page reports no title.
* **`<meta>` names that differ only in letter case let the last tag win.** Meta names do not depend on letter case, but `<meta name="Description">` followed by `<meta name="description">` gave the second value in the document metadata, and the frontmatter printed both. The names are now compared in any letter case, and the first tag wins in the frontmatter and the document metadata.
* **A `<head>` tag inside the body gave the two tiers different metadata.** The parser ignores a `<head>` tag once the body has started. Tier 1 read such a stray head when the page had no head of its own, and Tier 2 read it when the real head was empty. Both tiers now read only the first head before the body. The body starts at a `<body>` tag, at text, or at any tag other than the ones a head can hold, so `<p>x</p><head><title>Stray ` has no title. The document structure gives a metadata block only for the head the metadata reads. A leading UTF-8 byte order mark is dropped first, as a browser’s decoder drops it, so it does not start the body and no longer appears at the start of the output.
* **A `` text. The `base_href` and `canonical_url` fields now come only from the `<base>` element and `<link rel="canonical">`, and such a meta tag is an ordinary entry in `meta_tags`. A `<meta name="title">` still gives the `title` of a page without a `<title>` element, but it no longer replaces the text of one.
## \[3.15.1] - 2026-09-27
[Section titled “\[3.15.1\] - 2026-09-27”](#3151---2026-09-27)
### Fixed
[Section titled “Fixed”](#fixed-1)
* **`base_url` did not resolve a `<blockquote cite>`, and Tier 1 dropped the citation entirely.** `cite` is a destination the converter renders — Tier 2 emits it as a trailing `— <url>` line — but it was the one such destination `base_url` left alone, so a relative citation stayed relative. Tier 1’s blockquote handling read no attributes at all, so the same markup produced the citation on one tier and nothing on the other; a cited blockquote now bails to Tier 2, which is authoritative for it. Found while adopting `base_url` downstream, where a converter that resolves every destination except this one forces the caller to keep a whole link-rewriting pre-pass alive for it.
* **The Go binding could read a different OS thread’s FFI error slot.** `Convert`, `HeaderMetadata.IsValid` and the visitor entry point now pin the goroutine for the duration of the cgo call with `runtime.LockOSThread`. The FFI layer keeps its last-error state in a `thread_local!` (`crates/html-to-markdown-ffi/src/lib.rs:31`), so without pinning the Go runtime was free to reschedule the goroutine between the call that stamped the error and the `htm_last_error_code` read that reports it — surfacing a nil error for a call that had in fact failed. Emitted by alef 0.97.0; no Go API changed.
### Changed
[Section titled “Changed”](#changed-1)
* Repinned the `alef` generator to 0.97.0 and regenerated every binding. Apart from the Go thread pinning above, the only other generated change is the Kotlin Android Gradle wrapper moving from 9.7.1 to 9.8.0; everything else in the regeneration is version strings and provenance hashes.
* CI now gates the `docs-site` changelog mirror against `CHANGELOG.md`. The two are compared from the first `## [` heading onward rather than over `[Unreleased]` alone, because this repo releases straight out of `[Unreleased]` and leaves it empty on `main` — an Unreleased-only comparison would compare zero lines and pass while a released section drifted.
## \[3.15.0] - 2026-09-26
[Section titled “\[3.15.0\] - 2026-09-26”](#3150---2026-09-26)
### Added
[Section titled “Added”](#added-1)
* **`ConversionOptions::base_url`** resolves relative `href`/`src` destinations against a caller-supplied base URL, honoring a document’s own `<base href>` the way a browser does. Defaults to `None`, so output is byte-identical for callers who do not set it. Resolution happens identically in both the Tier 1 and Tier 2 rendering paths.
### Changed
[Section titled “Changed”](#changed-2)
* Upgraded `rmcp` to 3.4.1.
* Repinned the `alef` generator to 0.96.5 and regenerated every binding. Generator drift only; no public API of any binding changed.
* Split `converter/utility/content.rs` and `converter/inline/link.rs` (each over the 1000-line quality gate) into smaller modules, and reduced `convert_table_row`’s cyclomatic complexity by extracting its visitor-hook pre-pass into a separate function. No behavior change; every existing import path is preserved via re-exports.
### Fixed
[Section titled “Fixed”](#fixed-2)
* **The R binding compiles again.** `ConversionOptions::base_url` is the struct’s first `Option<String>`, and alef’s extendr backend assigned it a bare `String`, failing the whole R package build with `error[E0308]: expected Option<String>, found String`. Fixed in alef 0.96.5. It went unnoticed for two commits because two independent mechanisms each suppressed the leg. On the commit that introduced the line, `Test: R` was **cancelled**: `ci-e2e.yaml`’s `cancel-in-progress: true` group is keyed on the branch, so the next push to `main` killed the run before R finished. On the commit after that, `Test: R` was **skipped**: the leg is gated on a `packages/r/**`/`crates/html-to-markdown/**` paths filter that commit did not match. Neither state is a failure, so `CI E2E` reported success twice without ever compiling R.
* CI’s fixture-snippet validation now really validates the 341 Swift snippets. They had all been reporting `Unavailable` with `no such module 'HtmlToMarkdown'`: Swift 6.3 made `swiftbuild` the default build system, whose bin path holds the `.swiftmodule` files directly and emits no `Modules/` directory, while alef points `-I` at `<bin-path>/Modules`. The session now reconstructs that layout after building. The gate went red without any change to this tree, when the runner’s preinstalled Swift moved to 6.4.
## \[3.14.3] - 2026-09-19
[Section titled “\[3.14.3\] - 2026-09-19”](#3143---2026-09-19)
### Fixed
[Section titled “Fixed”](#fixed-3)
* **A whitespace-only inline wrapper nested inside another wrapper keeps its separator** ([#504](https://github.com/xberg-io/html-to-markdown/issues/504)). `<h2><strong>Alpha</strong><strong><em><br></em></strong>Beta</h2>` rendered `## **Alpha**Beta` from 3.14.2 on, where 3.14.1 kept the space, and a paragraph or table cell joined the words the same way. Issue #501 taught the shared wrapper emitter that a whitespace-only body at a line start contributes nothing, keyed on the destination buffer being empty – but the destination can also be an enclosing wrapper’s fresh scratch buffer, which is empty mid-line, so the inner `<em>`’s one space was dropped there and the outer `<strong>` came out empty. The line-start rule now fires only on the block’s own buffer, using the address test the text-node fallback already uses for the same distinction, so `<mark>`, `<ins>`, `<del>`, `<sub>` and `<sup>` wrappers move with it. A `<br>` inside a wrapper inside a table cell had the same shape on its own since before 3.14.2 – `<td>Alpha<em><br></em>Beta</td>` – and now keeps its space too; a cell’s own leading `<br>` still contributes nothing. Tier 1 bails on adjacent emphasis, so the change is Tier-2 only.
* **A newline inside nested transparent inline wrappers still separates the words around it** ([#505](https://github.com/xberg-io/html-to-markdown/issues/505)). `<p><i>Alpha</i><span><span>\n</span></span>Beta</p>` rendered `*Alpha*Beta` where a browser shows a space. Issues #430 and #491 taught the text-node fallback that a lone newline inside an inline wrapper separates words when the wrapper is followed by inline content, but the check looked one level up only: with a second wrapper the inner `<span>` is the last child of the outer one and the newline was dropped. The check now climbs through every transparent inline ancestor that has nothing after it and stops at the first block. Tier 1 already emitted the space, so this was a live cross-tier divergence; the tiers now agree.
* **An anchor that html5ever’s adoption agency splits around a block is emitted once, not twice** ([#493](https://github.com/xberg-io/html-to-markdown/issues/493)). `<a href="/o"><div><a href="/i">Inner</a></div></a>` rendered `[](/o)` and then `[](/o)[Inner](/i)`: the repair legitimately closes the outer `<a>` at the `<div>` and reconstructs it inside, and the clone reached the renderer indistinguishable from an authored element. A renderer rule keyed on shape would either drop a genuine empty anchor (`CommonMark` example 484) or a deliberately authored duplicate, so the fix is at parse time: every `<a>` start tag is stamped with a private origin id before the tree builder sees it, the clones inherit it, and on the repaired tree the halves of a split anchor with no content of their own are unwrapped in place. When no half has content the authored one is kept, so the destination still appears once as `[](/o)`; `<a href="/o"><div>Text<a href="/i">Inner</a></div></a>` keeps the half that carries `Text` and renders `[Text](/o)[Inner](/i)`. Input the repair never runs on, and an anchor the repair leaves whole, are unchanged.
## \[3.14.2] - 2026-09-18
[Section titled “\[3.14.2\] - 2026-09-18”](#3142---2026-09-18)
### Fixed
[Section titled “Fixed”](#fixed-4)
* **An `&` that would read as a character reference in a link destination or title now stays literal** ([#498](https://github.com/xberg-io/html-to-markdown/issues/498)). `CommonMark` decodes entity and numeric character references inside destinations and titles, so the decoded `?+` that `<img src="?+">` produced from 3.14.0 on re-parsed as `?+` – a different URL. `<a href>` and `title` had carried the same defect since 3.12, when they started decoding; only `src` was new to it. Such an `&` is now written back as `&`, the form 3.13 emitted and the one non-`CommonMark` consumers of the URL also read correctly. Only a reference the HTML5 decoder really recognises is touched: `?a&b` and `&foo;` are unchanged. Tier 1 wrote a link’s `href` straight into the output with no escaping at all, so it now shares Tier 2’s `append_url_destination`; that also ends a divergence unrelated to entities, where Tier 1 emitted `[T](/a b(c)` and `[T](/a(b)` against Tier 2’s `[T](</a b(c>)` and `[T](/a\(b)`.
* **An unmatched `[` in a link label or image `alt` is now escaped** ([#499](https://github.com/xberg-io/html-to-markdown/issues/499)). `CommonMark` accepts a bracket in a label only escaped or as a matched pair; an unmatched `]` was already escaped, an unmatched `[` was not. `<img alt="[A;B)" src="S">` rendered ``, which re-parses as a dangling `!` followed by a real `[A;B)](S)` link – the image was gone. The shared `escape_link_label` helper now escapes every opener left without a closer, so both tiers and every caller (links, images, `<graphic>`, SVG titles, embedded media) move together.
* **A run of ASCII whitespace at the start of a line is no longer emitted** ([#501](https://github.com/xberg-io/html-to-markdown/issues/501)). `<p>P</p><div><span> </span><img alt="A" src="S"></div>` rendered the image as `` indented by four columns, which `CommonMark` reads as an indented code block, so the image was lost. Issue #460 dropped leading whitespace at the start of a *paragraph*; a `<div>` never set that flag and the run fell through to the verbatim fallback. Leading ASCII whitespace on a line is never Markdown content, so the text-node fallback now drops it at a line start of the block’s own buffer, the `<div>` handler measures its content start the way `<p>` does so an inline wrapper’s empty scratch buffer is not mistaken for one (its single space must still reach the #481 handling), and a whitespace-only wrapper spliced in at a line start contributes nothing – `<p>A</p><p><i> </i>B</p>` no longer opens its second paragraph with a stray space. A multi-space run mid-line collapses to one space, as it already did between two inline siblings. A run carrying a decoded ` ` is untouched. Tier 1 already emitted every case this way.
* **A whitespace-only inline wrapper body no longer vanishes and joins the words around it** ([#502](https://github.com/xberg-io/html-to-markdown/issues/502)). `<b>Alpha</b><b><span>\n</span></b><b>Beta</b>` rendered `**AlphaBeta**`, and `Alpha<i>\n</i>Beta` rendered `AlphaBeta`, where a browser shows a space. Two drops of one shape: a newline-only text node returned early because the wrapper’s scratch buffer was empty – the buffer is fresh per wrapper, so its length says nothing about the document – and a `<br>` with nothing before it in that buffer left a bare newline that `chomp_inline` did not count as a space. Both now surface as the single separating space issue #481 already gives a literal `<b> </b>`, still suppressed after an existing space; a truly empty `<b></b>` still emits nothing. Tier 1 bails on every one of these shapes, so the change is Tier-2 only.
* **A headerless table whose rows have different cell counts is padded, not turned into a list** ([#500](https://github.com/xberg-io/html-to-markdown/issues/500)). `<table><tr><td>A</td><td>B</td></tr><tr><td>C</td></tr></table>` rendered `- A B` / `- C`: ragged row lengths alone classified a table as a *layout* table. A headerless table with a short row is ordinary tabular data far more often than it is an email-signature grid, and the regular renderer already pads a short row to the table’s width (issue #13), so it now renders `| A | B |`, `| --- | --- |`, `| C | |`. Layout still triggers on more than one nested table, `colspan`/`rowspan` combined with `border="0"`, a blank table, or a short table dense with links. Tier 1 keeps its stricter bail on ragged rows – it has no padding of its own – which only ever sends more input to the path that does. A layout row also **keeps an image as ``** instead of degrading it to alt text: the row is a list item, and list items and data cells keep images by default; only headings degrade them. `keepInlineImagesIn` is no longer needed for that (issue #433), though it still governs headings and links.
* **A layout row stays on one line across a `<br>` or a blank nested table.** A `<br>` inside a layout cell emitted a hard-break marker, and a nested table that rendered to nothing still emitted the blank line meant to separate content; either put a bare newline inside a list item’s line and ended the item. Both were latent – the Hacker News footer in the gh-121 fixture is `<img><table>bar</table><br>links`, and while the spacer image degraded to nothing every separator stayed suppressed – and keeping the image surfaced them. A `<br>` now follows the settled cell rule its `<div>`/`<p>` continuations already use (issue #470), and an empty table output writes no separator. Across the benchmark corpus this rejoined three split list items in one fixture and changed nothing else; the other movements are images now kept in layout rows and leading whitespace dropped at line starts (#501).
* **An anchor wrapping a table inside a layout cell keeps its inner links clickable** ([#503](https://github.com/xberg-io/html-to-markdown/issues/503)). Issue #490 renders a wrapped table as a separate block after the link, but refused inside inline contexts, and a cell of a table the layout heuristic turns into a bullet list converts as inline. The nested table was walked into the label instead, where the bracket escaping turned `[One](/one)` and `[Two](/two)` into text; only the outer destination survived. A layout cell is a list item’s text, not a link label, and it already holds a bare nested table on the lines after its bullet, so the deferred table now lands there the same way. Headings and true inline labels keep refusing. Tier 1 bails on a table opened inside a link, so this is Tier-2 only.
## \[3.14.1] - 2026-09-17
[Section titled “\[3.14.1\] - 2026-09-17”](#3141---2026-09-17)
### Fixed
[Section titled “Fixed”](#fixed-5)
* **A multi-line link label or image `alt` no longer has one of its lines read as block structure** ([#496](https://github.com/xberg-io/html-to-markdown/issues/496)). `CommonMark` parses block structure before inline structure (spec 0.31.2 appendix A), so a continuation line that looks like a block opener ends the paragraph the label lives in and the `[`/`![` never reaches its `]`. `` produced no image at all – it produced `<h2></p>`, with the image gone. A hard line break did not help, because it is inline and block parsing has already finished by then, so the reporter’s escaping workarounds could not work either. Measured against comrak, 14 of 18 opener shapes destroyed the construct: setext `-` and `=`, all three thematic breaks, ATX headings, both code fences, block quotes, all three bullet markers, both ordered-list delimiters, and HTML blocks. The first non-blank character of a continuation line is now backslash-escaped when that line would open a block *that can interrupt a paragraph* – ordered lists at their `.`/`)` delimiter, since a digit cannot carry an escape. Lines that open nothing are untouched: four columns of indent (indented code cannot interrupt a paragraph), a type-7 HTML block such as a bare `<span>`, `2. x`, `-x`, seven `#`. The label’s first line is never escaped – it is preceded on that same line by the caller’s own `[`/`). `<a href="H">A<br></a>B` renders as A, a line break, then B; the converter emitted `[A](H)B`, losing the break entirely. `[A \n](H)B` re-parses to exactly the original `<a href="H">A<br /></a>B` (verified against comrak), so the break belongs inside the label. Both tiers dropped it for the same reason expressed twice – the whole label was whitespace-trimmed, and once flattened a `" \n"` marker is indistinguishable from the incidental whitespace that really does belong before a `</a>` – and Tier 2 additionally never emitted a *leading* break at all, because its “nothing on this line yet” test compares a fresh label buffer’s length against the enclosing block’s start offset. A run of breaks at one edge still collapses to a single break (two adjacent markers would put a blank line in the label, and a blank line ends the paragraph, destroying the link), and a label of nothing but breaks still collapses to empty. A heading and a pipe-table cell are single-line and still fold every break to a space. The issue’s second example asks for `B[A \n](H)`, which moves the break to the far side of the label text; the break is preserved where the `<br>` actually was instead – `B[ \nA](H)`, which comrak renders back to the input DOM.
* Tier 1 no longer emits three spaces where Tier 2 emits one for a `<br>` inside a link inside a table cell (`| [A - B](H) |` against `| [A - B](H) |`). Tier 1 folded its hard-break marker late, in `close_table_cell`, which left the marker’s two spaces behind; it now folds in `close_link`, which is also what keeps the #496 escaping from firing on a label that is about to become single-line anyway.
* Generated Go and R e2e suites no longer assert against strings their fixtures never specified (alef pin 0.90.0 to 0.91.5). Two independent generator defects were corrupting fixture values on their way into test code: alef’s Go emitter rendered a multi-line value as a raw backtick literal and its own writer then trimmed the trailing whitespace off every physical line, so the three assertions carrying a Markdown two-space hard break read `[Alpha\n](url)Beta` where the fixture said `[Alpha \n](url)Beta`; and alef’s R emitter ran every plain string argument through the PascalCase-to-snake_case transform meant only for enum wire values, so `Alpha<span ...>` was emitted as `alpha<span ...>` and `Beta<a ...><br>Alpha</a>` as `beta<a ...><br>_alpha</a>`. The R defect had been silently wrong since the 3.14.0 `paragraph_whitespace_only_span_separates_words` fixture landed; it went unnoticed because the E2E workflow had skipped every language test job on the three preceding commits, so “green” meant “nothing ran”. Fixed upstream in alef 0.91.5 rather than by trimming the fixtures. The pin bump also carries alef 0.91.0-0.91.3, which for this repo is limited to a simpler argument-marshalling path in the Node visitor bridge (no API or behaviour change) and dropping its unused `tokio-util` dependency.
## \[3.14.0] - 2026-09-16
[Section titled “\[3.14.0\] - 2026-09-16”](#3140---2026-09-16)
### Changed
[Section titled “Changed”](#changed-3)
* **Upgraded `html5ever` to 0.40.1, which fixes silent content loss on the HTML repair path.** 0.40.0’s serializer dropped the leading `0xC2` byte of a two-byte UTF-8 sequence, corrupting every character in U+0080..U+00BF except NBSP – `§`, `©`, `°`, `·` among them. Because `repair_with_html5ever` serializes the repaired tree back to a string for the primary parser to re-read, a single such character made the whole re-parse fail and everything after it vanish. This repo was pinned to 0.39.0 to avoid it; 0.40.1 carries the upstream fix, verified here by building the same tree against both versions rather than by trusting the release note. A regression test now pins the behaviour with non-ASCII fixtures – the existing repair-path tests are ASCII-only and passed on the broken release, which is why the defect was invisible.
* Upgraded `rmcp` to 3.4.0. It deprecates the `ServerInfo` alias in favour of `ServerConfig` (the same type, renamed because it collided with the protocol’s own `serverInfo` field), so the MCP server’s `get_info` moved with it. No wire-visible change.
### Fixed
[Section titled “Fixed”](#fixed-6)
* **Character references in attribute values are now decoded** ([#494](https://github.com/xberg-io/html-to-markdown/issues/494)). `<a href>` was the only attribute in the converter that called the entity decoder, so every other user-visible attribute emitted its raw source text: `title="A&B"` reached the output as the literal `A&B`, and `alt="it's"` as `it's`. Twelve sites were affected – `title` on `<a>`, `<img>`, `<graphic>` and `<abbr>`; `alt` on `<img>` and `<graphic>`; `src` on `<img>`, `<audio>`, `<video>`, `<iframe>` and `<source>`; `cite` on `<blockquote>`; the `language-` class on a code fence; and `<meta content>` in extracted metadata. They were found by probing every attribute that reaches output, not by reading the ones that looked likely. Attribute reads now go through one shared accessor so a new attribute cannot reopen the gap. The Markdown escaping is unchanged and was never at fault – a literal `"` in a title was always escaped correctly; the decoded character simply never arrived. Tier 1 carried the same defect independently and moves in lockstep.
* **Three Tier-1 divergences that entity decoding made reachable.** Each was latent long before it could be triggered, and each is now pinned by a parity test. An `<img>` in a heading was emitted as `` by the fast scanner whenever `keepInlineImagesIn` was empty, where the DOM path correctly replaces it with its alt text – an empty list names no heading, so it permits nothing. A heading whose body merely *ended* in whitespace was never trimmed, because the trim only ran for bodies containing a newline; a decoded ` ` therefore survived where the DOM path dropped it. And a link title containing a quote was escaped as `"` rather than `\"`. The first two were found by the generated-corpus parity test over 3,000 documents, the third by a sweep over every character decoding newly makes reachable.
* **A wrapper element no longer defeats the nested-table fix** ([#488](https://github.com/xberg-io/html-to-markdown/issues/488)). A nested `<table>` inside a `<td>` was detected with a single-node tag-name test over the cell’s *direct* children, so wrapping it in a `<div>` bypassed the 3.12.4 deferral, the pipe escaping and the row fold all at once. The inner table’s raw `|` characters then read as the *outer* row’s cell boundaries on reparse – content loss, not a cosmetic diff. The nested-table *counter* has always descended through wrappers; the two now agree. The same line fixes the sibling-cell shape, which was corrupt in the same way.
* **Content after a table whose last row is never closed is no longer lost** ([#489](https://github.com/xberg-io/html-to-markdown/issues/489)). In `<table>...<tr></table><p>Visible footer</p>`, the primary parser discards a close tag that does not match the top of its open-element stack, so `</table>` vanished and the paragraph was adopted by the still-open `<tr>` – where the cell collector, which keeps only `td`/`th`, dropped it. Such a document now takes the same html5ever repair path that #336, #479 and #486 already use. A row that yields no cells also stops emitting a phantom empty row, so the next real row becomes the header, matching Tier 1. Two further shapes are fixed by the same gate: a second `<tr>` opened without closing the first (its row was silently dropped) and a `<td>` placed directly inside `<tbody>` (which produced no output at all). Text-only children are deliberately excluded from the gate, so a `<tr> </tr>` spacer does not pay for a full re-parse.
* **An anchor wrapping a table renders the table, not an escaped link label** ([#490](https://github.com/xberg-io/html-to-markdown/issues/490)). Any block content inside an `<a>` became link-label content, so `<a href="..."><table>...</table></a>` crushed the whole table into a single label – and the label escaper then correctly escaped the markdown that produced, leaving an unreadable run of `\|`. The escaping was never the bug; handing a table to the label builder was. The anchor’s direct children are now partitioned, the inline half forms the label and the deferred half renders as blocks after it. Only a deferred subtree that actually contains a `<table>` triggers this, and never inside a heading or an inline context, so every other anchor shape is byte-identical.
* **A whitespace-only inline wrapper still separates the words around it** ([#491](https://github.com/xberg-io/html-to-markdown/issues/491)). `Alpha<span style="white-space:pre">\n</span>13` rendered as `Alpha13`. The predicate added for #430 asks whether the *next sibling is an element*, so a bare text node after the wrapper took the failing path and the newline vanished. Tier 1 was already correct, so the two tiers disagreed on this input; they are now pinned together by a parity test. Note that the reported `white-space: pre` is incidental – that property is not implemented, and the defect reproduced without it, exactly as a browser collapses the newline to a space either way. The wrapper contributes a separator only when the next word butts straight up against it; text that already opens with whitespace supplies its own, and is left alone.
* **`keepInlineImagesIn` now means something for `<a>`** ([#492](https://github.com/xberg-io/html-to-markdown/issues/492)). The option was consulted for headings and for layout cells, but never for anchors, so an `<img>` inside a link that also held a block element was replaced by its alt text (or dropped entirely when it had none) no matter what the option said. Listing `"a"` now keeps the image as markdown, in both the block and inline anchor paths, and for `<graphic>` as well as `<img>`. The change is purely additive – it can turn an image on, never off – so output is byte-identical for anyone not naming `"a"` in the option. The Tier-1 scanner was updated in lockstep.
# CLI
The `html-to-markdown` CLI converts HTML files or URLs to Markdown from the command line.
## Installation
[Section titled “Installation”](#installation)
```bash
cargo install html-to-markdown-cli
```
Or grab the prebuilt binary via [cargo-binstall](https://github.com/cargo-bins/cargo-binstall):
```bash
cargo binstall html-to-markdown-cli
```
Or via Homebrew:
```bash
brew trust xberg-io/tap
brew install xberg-io/tap/html-to-markdown
```
Or on Windows via [Scoop](https://scoop.sh):
```powershell
scoop bucket add xberg https://github.com/xberg-io/scoop-bucket
scoop install html-to-markdown
```
## Basic Usage
[Section titled “Basic Usage”](#basic-usage)
```bash
# Convert stdin
echo '<h1>Title</h1><p>Content</p>' | html-to-markdown
# Convert a file
html-to-markdown input.html
# Convert a file and save output
html-to-markdown input.html -o output.md
# Fetch and convert a remote URL
html-to-markdown --url https://example.com > output.md
```
## Input
[Section titled “Input”](#input)
| Flag | Description |
| --------------------------- | -------------------------------------------------- |
| `FILE` | Input HTML file. Use `-` or omit for stdin. |
| `--url URL` | Fetch HTML from a URL (alternative to file/stdin). |
| `--user-agent UA` | Custom User-Agent header when using `--url`. |
| `-e`, `--encoding ENCODING` | Input character encoding (default: `utf-8`). |
## Output
[Section titled “Output”](#output)
| Flag | Description |
| ------------------------------ | -------------------------------------------------------- |
| `-o`, `--output FILE` | Write output to file (default: stdout). |
| `-f`, `--output-format FORMAT` | Output format: `markdown` (default), `djot`, or `plain`. |
## Heading Options
[Section titled “Heading Options”](#heading-options)
| Flag | Values | Default | Description |
| ----------------------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `--heading-style STYLE` | `atx`, `underlined`, `atx-closed` | `atx` | How headings are formatted. `atx` uses `#` prefixes; `underlined` uses `===`/`---` for h1/h2. |
## List Options
[Section titled “List Options”](#list-options)
| Flag | Values | Default | Description |
| ------------------------- | --------------- | -------- | ------------------------------------------------------- |
| `--list-indent-type TYPE` | `spaces`, `tab` | `spaces` | Indentation character for nested lists. |
| `--list-indent-width N` | 1–8 | `2` | Spaces per nesting level. |
| `-b`, `--bullets CHARS` | e.g. `-*+` | `-*+` | Characters to cycle through for unordered list markers. |
## Text Formatting
[Section titled “Text Formatting”](#text-formatting)
| Flag | Values | Default | Description |
| --------------------------- | -------------------------------------- | -------------- | ------------------------------------------------- |
| `--strong-em-symbol CHAR` | `*`, `_` | `*` | Symbol for bold and italic. |
| `--newline-style STYLE` | `backslash`, `spaces` | `spaces` | How `<br>` tags are rendered. |
| `--sub-symbol SYMBOL` | any string | `""` | Wrapper symbol for `<sub>` text. |
| `--sup-symbol SYMBOL` | any string | `""` | Wrapper symbol for `<sup>` text. |
| `--highlight-style STYLE` | `double-equal`, `html`, `bold`, `none` | `double-equal` | Rendering of `<mark>` elements. |
| `--no-expand-abbreviations` | — | off | Write the text of an `<abbr>` without its title. |
| `--no-blockquote-citations` | — | off | Write a blockquote without its `cite` URL. |
| `--escape-asterisks` | — | off | Escape `*` characters. |
| `--escape-underscores` | — | off | Escape `_` characters. |
| `--escape-misc` | — | off | Escape `[`, `]`, `<`, `>`, `#`, etc. |
| `--escape-ascii` | — | off | Escape all ASCII punctuation (strict CommonMark). |
## Code Blocks
[Section titled “Code Blocks”](#code-blocks)
| Flag | Values | Default | Description |
| ---------------------------- | --------------------------------- | ----------- | -------------------------------------------- |
| `--code-block-style STYLE` | `indented`, `backticks`, `tildes` | `backticks` | Format for multi-line code blocks. |
| `-l`, `--code-language LANG` | any string | `""` | Default language tag for fenced code blocks. |
## Links
[Section titled “Links”](#links)
| Flag | Values | Default | Description |
| -------------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--no-autolinks` | — | off | Disable autolink conversion. By default, when link text equals the href, the output is `<url>`. Pass this flag to emit `[url](url)` instead. |
| `--default-title` | — | off | Use href as link title when no `title` attribute exists. |
| `--link-style STYLE` | `inline`, `reference` | `inline` | `inline` emits `[text](url)`. `reference` emits `[text][1]` with numbered definitions at the end of the document. |
| `--url-escape-style STYLE` | `angle`, `percent` | `angle` | `angle` wraps destinations containing spaces or newlines in `<...>`. `percent` percent-encodes every character that is not RFC 3986 unreserved or `/`. |
## Images
[Section titled “Images”](#images)
| Flag | Description |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--keep-inline-images-in ELEMENTS` | Comma-separated element names where images stay as `` (e.g. `a,strong`). |
| `--skip-images` | Drop all `<img>` elements entirely. No `` output, no alt-text fallback. |
| `--inline-data-media CHOICE` | What to write for an image, media element, or link, whose address is a `data:` URL: `keep` (default, the URL with its payload), `alt-text-only`, or `drop-element`. For a link, `alt-text-only` and `drop-element` both write its text with no address. |
| `--hidden-content CHOICE` | Which text that a browser does not show at first to keep: `drop` (default, none), `reachable` (elements hidden by the `hidden` attribute or an inline style, and declarative shadow roots), or `all` (also `<template>` and `<noscript>` content). Scripts and style sheets are never written. |
| `--max-image-size BYTES` | Skip inline images whose decoded payload exceeds this size. Default `5242880` (5 MB). Requires `--extract-inline-images`. |
| `--capture-svg` | Capture inline `<svg>` elements as extracted images. Requires `--extract-inline-images`. |
| `--no-infer-dimensions` | Skip inferring image width and height from the decoded payload when the HTML omits them. Requires `--extract-inline-images`. |
## Tables
[Section titled “Tables”](#tables)
| Flag | Description |
| ------------------ | ------------------------------------------------------------------------------- |
| `--br-in-tables` | Preserve line breaks in table cells as `<br>` rather than converting to spaces. |
| `--compact-tables` | Emit compact GFM tables without column-padding alignment. |
## Whitespace
[Section titled “Whitespace”](#whitespace)
| Flag | Values | Default | Description |
| ------------------------ | ---------------------- | ------------ | ------------------------------------------------- |
| `--whitespace-mode MODE` | `normalized`, `strict` | `normalized` | Whitespace handling strategy. |
| `--strip-newlines` | — | off | Remove all newlines from input before processing. |
## Wrapping
[Section titled “Wrapping”](#wrapping)
| Flag | Values | Default | Description |
| ---------------- | ------ | ------- | ---------------------------- |
| `-w`, `--wrap` | — | off | Enable output line wrapping. |
| `--wrap-width N` | 20–500 | `80` | Column width for wrapping. |
## Element Handling
[Section titled “Element Handling”](#element-handling)
| Flag | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--convert-as-inline` | Treat block elements as inline (no paragraph breaks). |
| `--strip-tags TAGS` | Comma-separated tags to strip (text content preserved, no Markdown conversion). |
| `--preserve-tags TAGS` | Comma-separated tags to emit verbatim as raw HTML instead of converting. |
| `--exclude-selectors SELECTORS` | Comma-separated CSS selectors. Matching elements and their descendants are removed before conversion (e.g. `.ad,#sidebar`). A selector with a combinator (`.menu a`, `div > p`) or a pseudo-class matches nothing. |
| `--max-depth N` | Silently truncate subtrees beyond this DOM nesting depth. Omit for unlimited depth. |
## Metadata
[Section titled “Metadata”](#metadata)
| Flag | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--extract-metadata` | Prepend a metadata comment block (title, description, Open Graph, links, images) to the Markdown output. In `--json` mode, populates the `metadata` field. |
## JSON Output Available by v3.6
[Section titled “JSON Output Available by v3.6”](#json-output-available-by-v36)
`--json` swaps the default Markdown output for a full `ConversionResult` object: `content`, `metadata`, `tables`, `document`, `images`, and `warnings` on a single JSON value. The flags in this section control which fields are populated.
| Flag | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--json` | Output a full `ConversionResult` as JSON instead of Markdown. |
| `--include-structure` | Populate `document` with the parsed semantic tree. Requires `--json`. |
| `--extract-inline-images` | Populate `images` with extracted data URIs and SVGs. Requires `--json`. |
| `--no-content` | Skip Markdown rendering. `content` is empty, metadata and structure still populate. Requires `--json`. |
| `--show-warnings` | Print each processing warning to stderr as `Warning [<kind>]: <message>`. Works with or without `--json`. |
## Preprocessing
[Section titled “Preprocessing”](#preprocessing)
| Flag | Values | Default | Description |
| -------------------- | ----------------------------------- | ---------- | ------------------------------------------------------------------------- |
| `-p`, `--preprocess` | — | off | Clean up HTML before conversion. |
| `--preset LEVEL` | `minimal`, `standard`, `aggressive` | `standard` | Preprocessing aggressiveness (requires `--preprocess`). |
| `--keep-navigation` | — | off | Preserve `<nav>` elements during preprocessing (requires `--preprocess`). |
| `--keep-forms` | — | off | Preserve form elements during preprocessing (requires `--preprocess`). |
## Debugging
[Section titled “Debugging”](#debugging)
| Flag | Description |
| --------- | ------------------------------------------- |
| `--debug` | Output diagnostic warnings and information. |
## Advanced
[Section titled “Advanced”](#advanced)
| Flag | Values | Default | Description |
| -------------------------- | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tier-strategy STRATEGY` | `auto`, `tier2` | `auto` | `auto` picks the fastest conversion path the input allows. `tier2` always takes the DOM-walk path. Output is identical either way; this exists for benchmarking and bug isolation. |
## Shell Completions and Man Page
[Section titled “Shell Completions and Man Page”](#shell-completions-and-man-page)
```bash
# Generate shell completions
html-to-markdown --generate-completion bash > html-to-markdown.bash
html-to-markdown --generate-completion zsh > _html-to-markdown
html-to-markdown --generate-completion fish > html-to-markdown.fish
# Generate man page
html-to-markdown --generate-man > html-to-markdown.1
```
## Examples
[Section titled “Examples”](#examples)
```bash
# Web scraping with aggressive preprocessing
html-to-markdown page.html --preprocess --preset aggressive
# Extract full structured result as JSON
html-to-markdown input.html --json \
--extract-metadata --include-structure \
-o output.json
# Discord/Slack-friendly output (2-space list indents)
html-to-markdown input.html --list-indent-width 2
# Custom heading and list styles
html-to-markdown input.html \
--heading-style atx \
--bullets '*' \
--list-indent-width 2
# Fetch and convert with Djot output
html-to-markdown --url https://example.com --output-format djot
```
## CLI Flag ↔ ConversionOptions Mapping
[Section titled “CLI Flag ↔ ConversionOptions Mapping”](#cli-flag--conversionoptions-mapping)
Each CLI flag has a corresponding `ConversionOptions` field. Library users can cross-reference here when translating a CLI invocation to code (or vice versa).
| CLI Flag | `ConversionOptions` field | Notes |
| ------------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
| `--output-format FORMAT` | `output_format` | `"markdown"` \| `"djot"` \| `"plain"` |
| `--heading-style STYLE` | `heading_style` | `"atx"` \| `"underlined"` \| `"atx-closed"` |
| `--list-indent-type TYPE` | `list_indent_type` | `"spaces"` \| `"tab"` |
| `--list-indent-width N` | `list_indent_width` | integer |
| `--bullets CHARS` | `bullets` | string |
| `--strong-em-symbol CHAR` | `strong_em_symbol` | `"*"` \| `"_"` |
| `--newline-style STYLE` | `newline_style` | `"backslash"` \| `"spaces"` |
| `--sub-symbol SYMBOL` | `sub_symbol` | string |
| `--sup-symbol SYMBOL` | `sup_symbol` | string |
| `--highlight-style STYLE` | `highlight_style` | `"double-equal"` \| `"html"` \| `"bold"` \| `"none"` |
| `--escape-asterisks` | `escape_asterisks` | boolean flag |
| `--escape-underscores` | `escape_underscores` | boolean flag |
| `--escape-misc` | `escape_misc` | boolean flag |
| `--escape-ascii` | `escape_ascii` | boolean flag |
| `--code-block-style STYLE` | `code_block_style` | `"indented"` \| `"backticks"` \| `"tildes"` |
| `-l, --code-language LANG` | `code_language` | string |
| `--no-autolinks` | `autolinks` | inverted: flag sets `autolinks = false`; default is `true` |
| `--no-expand-abbreviations` | `expand_abbreviations` | inverted: flag sets `expand_abbreviations = false`; default is `true` |
| `--no-blockquote-citations` | `include_blockquote_citations` | inverted: flag sets `include_blockquote_citations = false`; default is `true` |
| `--default-title` | `default_title` | boolean flag |
| `--link-style STYLE` | `link_style` | `"inline"` \| `"reference"` |
| `--url-escape-style STYLE` | `url_escape_style` | `"angle"` \| `"percent"` |
| `--keep-inline-images-in ELEMS` | `keep_inline_images_in` | comma-separated tag list |
| `--skip-images` | `skip_images` | boolean flag |
| `--inline-data-media CHOICE` | `inline_data_media` | `"keep"` \| `"alt_text_only"` \| `"drop_element"` |
| `--hidden-content CHOICE` | `hidden_content` | `"drop"` \| `"reachable"` \| `"all"` |
| `--max-image-size BYTES` | `max_image_size` | integer; default `5242880` |
| `--capture-svg` | `capture_svg` | boolean flag |
| `--no-infer-dimensions` | `infer_dimensions` | inverted: flag sets `infer_dimensions = false`; default is `true` |
| `--br-in-tables` | `br_in_tables` | boolean flag |
| `--compact-tables` | `compact_tables` | boolean flag |
| `--whitespace-mode MODE` | `whitespace_mode` | `"normalized"` \| `"strict"` |
| `--strip-newlines` | `strip_newlines` | boolean flag |
| `-w, --wrap` | `wrap` | boolean flag |
| `--wrap-width N` | `wrap_width` | integer |
| `--convert-as-inline` | `convert_as_inline` | boolean flag |
| `--strip-tags TAGS` | `strip_tags` | comma-separated tag list |
| `--preserve-tags TAGS` | `preserve_tags` | comma-separated tag list |
| `--exclude-selectors SELECTORS` | `exclude_selectors` | comma-separated CSS selector list |
| `--max-depth N` | `max_depth` | integer |
| `--extract-metadata` | `extract_metadata` | boolean flag |
| `--include-structure` | `include_document_structure` | boolean flag; `--json` only |
| `--extract-inline-images` | `extract_images` | boolean flag; `--json` only |
| `-p, --preprocess` | `preprocess` | boolean flag |
| `--preset LEVEL` | `preset` | `"minimal"` \| `"standard"` \| `"aggressive"` |
| `--keep-navigation` | `keep_navigation` | boolean flag |
| `--keep-forms` | `keep_forms` | boolean flag |
| `-e, --encoding ENCODING` | `encoding` | CLI only — decoded before `convert()` |
| `--tier-strategy STRATEGY` | `tier_strategy` | `"auto"` \| `"tier2"` |
| `--debug` | `debug` | CLI only — diagnostic output to stderr |
Flags without a `ConversionOptions` counterpart: `FILE`, `--url`, `--user-agent`, `-o/--output`, `--json`, `--no-content`, `--show-warnings`, `--generate-completion`, `--generate-man`.
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Architecture
> html-to-markdown architecture — Rust core, polyglot bindings, single-pass DOM walk, FFI surface, feature flags. Where the conversion logic lives and how each language reaches it.
html-to-markdown has a Rust core plus 15 generated packages. All language surfaces call the same `convert()` function — there is no per-language conversion logic.
## Crate layout
[Section titled “Crate layout”](#crate-layout)
The repository is a Cargo workspace. The core library and every native binding live under `crates/`; thin distribution wrappers live under `packages/`.
```text
crates/
├── html-to-markdown/ # Core library (html-to-markdown-rs on crates.io)
├── html-to-markdown-cli/ # CLI binary
├── html-to-markdown-ffi/ # C FFI shared library (libhtml_to_markdown, headers via cbindgen)
├── html-to-markdown-node/ # Node.js / TypeScript binding (NAPI-RS)
├── html-to-markdown-py/ # Python binding (PyO3)
├── html-to-markdown-php/ # PHP extension (ext-php-rs)
├── html-to-markdown-wasm/ # WebAssembly binding (wasm-bindgen)
└── html-to-markdown-rs-jni/ # JNI bridge used by Kotlin Android
```
Go, Ruby, Java, C#, Elixir, R, Swift, Dart, Kotlin Android, and Zig live under `packages/` and call Rust through their generated backend or `libhtml_to_markdown`. The Rust workspace version in the root `Cargo.toml` is the single source of truth — all binding manifests inherit it.
## Core library
[Section titled “Core library”](#core-library)
`crates/html-to-markdown/` is the only place where conversion logic lives. Its public API is one function:
```rust
pub fn convert(html: &str, options: Option<ConversionOptions>) -> Result<ConversionResult>
```
See [Conversion pipeline](/concepts/pipeline/) for the per-stage breakdown.
## Binding mechanisms
[Section titled “Binding mechanisms”](#binding-mechanisms)
Each language reaches Rust via one of two routes: direct embedding (the Rust code compiles into the host language’s native extension module) or the C FFI shared library (the host language loads `libhtml_to_markdown` at runtime).
### Direct embedding
[Section titled “Direct embedding”](#direct-embedding)
| Language | Mechanism | Crate |
| -------------------- | ----------------------------------------------------------------------- | ----------------------- |
| Python | [PyO3](https://pyo3.rs) extension module | `html-to-markdown-py` |
| TypeScript / Node.js | [NAPI-RS](https://napi.rs) Node-API addon | `html-to-markdown-node` |
| PHP | [ext-php-rs](https://docs.rs/ext-php-rs) PHP extension | `html-to-markdown-php` |
| Ruby | [Magnus](https://github.com/matsadler/magnus) gem extension | `packages/ruby` |
| Elixir | [Rustler](https://github.com/rusterlium/rustler) NIF | `packages/elixir` |
| R | [extendr](https://extendr.github.io) R extension | `packages/r` |
| WebAssembly | [wasm-bindgen](https://rustwasm.github.io/docs/wasm-bindgen/) | `html-to-markdown-wasm` |
| Swift | [swift-bridge](https://github.com/chinedufn/swift-bridge) package | `packages/swift` |
| Dart | [flutter_rust_bridge](https://cjycode.com/flutter_rust_bridge/) package | `packages/dart` |
For these, the conversion function compiles directly into the native extension. The host language never sees the C ABI.
### Via libhtml_to_markdown (C FFI)
[Section titled “Via libhtml_to_markdown (C FFI)”](#via-libhtml_to_markdown-c-ffi)
| Language | Mechanism | Notes |
| -------------- | ---------------------------------------- | ------------------------------------------------------- |
| Go | cgo | Bundles `libhtml_to_markdown.a` in the Go module. |
| Java | Foreign Function & Memory API (Java 25+) | Extracts the shared library from the JAR at startup. |
| C# | P/Invoke (`DllImport`) | Loads `libhtml_to_markdown` via `NativeLibrary`. |
| Kotlin Android | JNI bridge | Android AAR; JVM Kotlin users consume the Java package. |
| Zig | C ABI | Zig package wraps the C FFI symbols. |
| C | Direct link | Header `html_to_markdown.h`, prefix `htm_*`/`HTM*`. |
The FFI crate exposes a minimal, null-safe C API (`htm_convert`, `htm_conversion_result_*`, `htm_free_string`, …) and catches any Rust panics at the boundary, converting them to `ConversionError::Panic` rather than letting them unwind across the ABI.
## Feature flags
[Section titled “Feature flags”](#feature-flags)
The core library compiles with five Cargo features. Bindings enable the subset they expose.
| Feature | What it gates |
| --------------- | ------------------------------------------------------------ |
| `metadata` | Metadata extraction and `HtmlMetadata` types (on by default) |
| `visitor` | `HtmlVisitor` trait and `ConversionError::Visitor` |
| `inline-images` | Data-URI decoder and inline SVG extractor |
| `serde` | `Serialize`/`Deserialize` on option and result types |
| `full` | All four optional features combined |
Rust and WASM expose inline image extraction when built with `inline-images`. Generated native bindings may omit the Rust-only `InlineImage` payload even when they expose metadata for ordinary images.
## Thread safety and allocation
[Section titled “Thread safety and allocation”](#thread-safety-and-allocation)
The core library is stateless and does not use global state. `convert()` is safe to call from multiple threads simultaneously. Each call allocates and frees its own buffers independently.
Bindings that cross the C FFI boundary use opaque handles returned by `htm_*` constructors and freed by matching `htm_*_free` functions. Strings returned across the FFI must be released with `htm_free_string`. The Go, Java, and C# bindings handle this internally.
## Ecosystem fit
[Section titled “Ecosystem fit”](#ecosystem-fit)
html-to-markdown is consumed by [Xberg](https://docs.xberg.io) (as the HTML extractor in the document intelligence pipeline) and [crawlberg](https://docs.crawlberg.xberg.io) (as the conversion stage after page fetch). The output `ConversionResult` is intentionally close in shape to Xberg’s `ExtractionResult` so the two compose without translation.
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Conversion pipeline
> How html-to-markdown converts HTML to Markdown — preprocessing, parsing, single-pass DOM walk, post-processing, and structured extraction.
Every call to `convert()` runs the same five-stage pipeline. There is no second pass and no separate analysis phase.
```mermaid
flowchart LR
A[HTML input] --> B[Preprocess]
B --> C[Parse]
C --> D[Single-pass DOM walk]
D --> E[Post-process]
D --> F[Extract tables, metadata, images]
E --> G[ConversionResult.content]
F --> H[ConversionResult.tables / .metadata / .images]
```
## 1. Preprocessing
[Section titled “1. Preprocessing”](#1-preprocessing)
Scripts and styles are stripped with a fast byte-scanner pass before parsing begins. If the `preprocess` option is `true`, navigation elements (`<nav>`, plus `<header>` / `<footer>` / `<aside>` that carry navigation hints in their class or id) are also dropped.
The preprocessing pass is conservative — it only removes elements that would never contribute to text output. See the [Configuration → Preprocessing](/configuration/#preprocessing) section for the exact rules.
## 2. Parsing
[Section titled “2. Parsing”](#2-parsing)
The HTML is parsed by [html5ever](https://crates.io/crates/html5ever), the same WHATWG-spec-compliant parser used by Servo. The parser builds an in-memory tree rooted at a document node and applies browser-compatible error recovery so malformed input degrades gracefully.
Metadata extraction (`<title>`, `<meta>`, `<link>`, Open Graph, JSON-LD, …) runs in a separate fast pass using [astral-tl](https://crates.io/crates/astral-tl), a high-performance tokenizer.
The library does not stream: the entire HTML is parsed before the DOM walk starts. For very large documents (multi-MB) this is the dominant memory cost.
## 3. Single-pass DOM walk
[Section titled “3. Single-pass DOM walk”](#3-single-pass-dom-walk)
The walk is pre-order. For every node, an element-specific handler appends to the output buffer. The same traversal:
* Writes Markdown to a `String` buffer.
* Dispatches to the registered [`HtmlVisitor`](/concepts/plugin-system/) (if any) and applies the returned `VisitResult`.
* Collects `<table>` elements into `result.tables`.
* Collects inline images into `result.images` (when `extract_images` is enabled).
* Builds `result.document` when `include_document_structure` is enabled.
There is no intermediate AST. The output buffer grows steadily; the only cost is the parsed DOM and the growing string.
## 4. Post-processing
[Section titled “4. Post-processing”](#4-post-processing)
Whitespace normalization, trailing-newline cleanup, reference-style link definition collection, and format-specific tweaks (Djot or plain text) are applied to the accumulated output buffer. This stage runs once on the final string and is cheap.
## 5. Extraction assembly
[Section titled “5. Extraction assembly”](#5-extraction-assembly)
Tables, inline images, metadata, and document structure are assembled into the final `ConversionResult`:
| Field | Type | Populated when |
| ---------- | --------------------------- | ----------------------------------------- |
| `content` | `Option<String>` | always (None only for extraction-only) |
| `metadata` | `HtmlMetadata` | always (feature `metadata` enabled) |
| `tables` | `Vec<TableData>` | always |
| `images` | `Vec<InlineImage>` | `extract_images: true` |
| `document` | `Option<DocumentStructure>` | `include_document_structure: true` |
| `warnings` | `Vec<ProcessingWarning>` | always (non-fatal issues during the walk) |
## Output formats
[Section titled “Output formats”](#output-formats)
The same pipeline produces all three output formats. The `output_format` option only changes the rendering handlers in stage 3:
* **Markdown** (default) — CommonMark-compatible.
* **Djot** — uses `*emphasis*` and `_strong_` instead of Markdown’s asterisk-doubling.
* **Plain** — strips all markup, link targets, and list markers; returns visible text only.
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Plugin system (visitors)
> html-to-markdown plugin system — the HtmlVisitor trait, 40 callbacks, VisitResult variants, and binding support.
The visitor system is the library’s extensibility point. Implement `HtmlVisitor` and you can replace, skip, or augment how any HTML element becomes Markdown. No fork required.
Rust users opt in with `features = ["visitor"]`. Bindings expose the same hooks only where the generated backend supports trait handles; Kotlin Android excludes visitor support.
## The trait
[Section titled “The trait”](#the-trait)
```rust
pub trait HtmlVisitor: std::fmt::Debug + Send {
fn visit_text(&mut self, ctx: &NodeContext, text: &str) -> VisitResult { VisitResult::Continue }
fn visit_element_start(&mut self, ctx: &NodeContext) -> VisitResult { VisitResult::Continue }
fn visit_element_end(&mut self, ctx: &NodeContext, output: &str) -> VisitResult { VisitResult::Continue }
fn visit_link(&mut self, ctx: &NodeContext, href: &str, text: &str, title: Option<&str>) -> VisitResult { VisitResult::Continue }
fn visit_image(&mut self, ctx: &NodeContext, src: &str, alt: &str, title: Option<&str>) -> VisitResult { VisitResult::Continue }
fn visit_heading(&mut self, ctx: &NodeContext, level: u32, text: &str, id: Option<&str>) -> VisitResult { VisitResult::Continue }
// ... 34 more element-specific methods, all with `Continue` defaults
}
```
40 methods in total: text and element pre/post hooks plus a method per HTML element family (links, images, headings, lists, code, tables, definition lists, and forms/media/figures). Override only the methods you need.
## VisitResult
[Section titled “VisitResult”](#visitresult)
Every callback returns a `VisitResult`. There are five variants:
| Variant | Effect |
| ---------------- | ----------------------------------------------------------------------------------- |
| `Continue` | Use the default rendering. Default for every method. |
| `Custom(String)` | Replace the default output with the supplied string. The visitor owns this subtree. |
| `Skip` | Drop the element and all of its children. |
| `PreserveHtml` | Emit the raw HTML for this element verbatim, without conversion. |
| `Error(String)` | Halt conversion. Surfaces as `ConversionError::Visitor` in Rust. |
`visit_text` is hot — it fires for every text node, often 100+ times per page. Return `Continue` fast when you don’t care, and avoid allocations in the hot path.
## Registration
[Section titled “Registration”](#registration)
In Rust, attach a visitor through the options builder:
```rust
use html_to_markdown_rs::visitor::{HtmlVisitor, VisitorHandle};
use html_to_markdown_rs::ConversionOptions;
use std::sync::{Arc, Mutex};
let visitor: VisitorHandle = Arc::new(Mutex::new(MyVisitor::default()));
let options = ConversionOptions::builder().visitor(Some(visitor)).build();
```
In other languages, the same hook is reached by passing a visitor object to the options builder. For binding-specific examples see [Guides → Visitor pattern](/visitor/).
## Cost when unused
[Section titled “Cost when unused”](#cost-when-unused)
Without a visitor registered, the dispatch site short-circuits and the default handler runs directly — there is no virtual call, no allocation, no extra branch on the hot path. The visitor feature is opt-in for Rust users specifically so consumers who never need it pay nothing.
## Across the C FFI
[Section titled “Across the C FFI”](#across-the-c-ffi)
When a visitor crosses the C FFI boundary, the C layer exposes a `HTMHtmVisitorCallbacks` struct of function pointers. The Rust side wraps each callback in a bridge that marshals strings and `NodeContext` fields and translates the returned status code into a `VisitResult`. The status codes are `HTM_VISIT_CONTINUE`, `HTM_VISIT_SKIP`, `HTM_VISIT_PRESERVE_HTML`, `HTM_VISIT_CUSTOM`, and `HTM_VISIT_ERROR`.
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Configuration
All options are passed via `ConversionOptions` (builder pattern in Rust, keyword arguments in Python/Ruby/Elixir/R, object literal in TypeScript, struct in Go/Java/C#, constructor in PHP).
## Options Reference
[Section titled “Options Reference”](#options-reference)
### Output Format
[Section titled “Output Format”](#output-format)
| Option | Type | Default | Description |
| --------------- | ------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
| `output_format` | `"markdown"` \| `"djot"` \| `"plain"` | `"markdown"` | Target output format. `"plain"` strips all markup and link targets, returning only visible text. |
### Headings
[Section titled “Headings”](#headings)
| Option | Type | Default | Description |
| --------------- | ------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `heading_style` | `"atx"` \| `"underlined"` \| `"atx_closed"` | `"atx"` | ATX uses `#` prefixes (`# H1`). Underlined uses `===`/`---` for h1/h2. ATX closed adds trailing hashes (`# H1 #`). |
### Lists
[Section titled “Lists”](#lists)
| Option | Type | Default | Description |
| ------------------- | --------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `list_indent_type` | `"spaces"` \| `"tab"` | `"spaces"` | Indentation character for nested lists. |
| `list_indent_width` | `int` | `2` | Number of spaces per nesting level (when using spaces). Not range-checked by the core library. |
| `bullets` | `string` | `"-*+"` | Characters to cycle through for unordered list markers. For example `"-*+"` uses `-` at level 1, `*` at level 2, `+` at level 3. |
### Text Formatting
[Section titled “Text Formatting”](#text-formatting)
| Option | Type | Default | Description |
| ------------------ | ---------------------------------------------------- | ---------------- | --------------------------------------------------------------------------- |
| `strong_em_symbol` | `"*"` \| `"_"` | `"*"` | Symbol used for bold (`**text**`) and italic (`*text*`). |
| `newline_style` | `"spaces"` \| `"backslash"` | `"spaces"` | How to render `<br>` tags: two trailing spaces or backslash at end of line. |
| `sub_symbol` | `string` | `""` | Symbol to wrap `<sub>` content (e.g. `"~"` → `~text~`). |
| `sup_symbol` | `string` | `""` | Symbol to wrap `<sup>` content (e.g. `"^"` → `^text^`). |
| `highlight_style` | `"double-equal"` \| `"html"` \| `"bold"` \| `"none"` | `"double-equal"` | Rendering of `<mark>` elements. |
### Escaping
[Section titled “Escaping”](#escaping)
| Option | Type | Default | Description |
| -------------------- | ------ | ------- | ------------------------------------------------------------ |
| `escape_asterisks` | `bool` | `false` | Escape `*` characters in text. |
| `escape_underscores` | `bool` | `false` | Escape `_` characters in text. |
| `escape_misc` | `bool` | `false` | Escape characters like `[`, `]`, `<`, `>`, `#`, etc. |
| `escape_ascii` | `bool` | `false` | Escape all ASCII punctuation (strict CommonMark compliance). |
### Code Blocks
[Section titled “Code Blocks”](#code-blocks)
| Option | Type | Default | Description |
| ------------------ | ------------------------------------------- | ------------- | ------------------------------------------------------------------------- |
| `code_block_style` | `"indented"` \| `"backticks"` \| `"tildes"` | `"backticks"` | How to format multi-line code blocks. |
| `code_language` | `string` | `""` | Default language tag for fenced code blocks without an explicit language. |
### Links
[Section titled “Links”](#links)
| Option | Type | Default | Description |
| ------------------ | --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autolinks` | `bool` | `true` | When link text equals the href, emit `<url>` instead of `[url](url)`. |
| `default_title` | `bool` | `false` | Use the href as link title when no `title` attribute is present. |
| `link_style` | `"inline"` \| `"reference"` | `"inline"` | `inline` emits `[text](url)`. `reference` emits `[text][1]` with numbered definitions collected at the end of the document. |
| `url_escape_style` | `"angle"` \| `"percent"` | `"angle"` | Escaping for link/image URL destinations. `angle` wraps destinations containing spaces or newlines in `<...>`. `percent` percent-encodes every character that is not an RFC 3986 unreserved character or `/`. |
### Images
[Section titled “Images”](#images)
| Option | Type | Default | Description |
| ----------------------- | ------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keep_inline_images_in` | `array` | `[]` | Element names where images should be kept as Markdown `` rather than converted to alt text. |
| `extract_images` | `bool` | `false` | Extract data URIs and embedded SVGs. Rust and WASM expose inline images when built with `inline-images`; generated native bindings may omit the Rust-only image payload. |
| `skip_images` | `bool` | `false` | Drop image elements entirely. No `` output, no alt-text fallback. |
| `inline_data_media` | `"keep"` \| `"alt_text_only"` \| `"drop_element"` | `"keep"` | What to write for an `<img>`, `<graphic>`, inline `<svg>`, `<video>`, `<audio>`, `<iframe>`, or a link, whose address is a `data:` URL. `keep` writes the URL with its payload. `alt_text_only` writes the alt text (the title of an `<svg>`, the fallback content of `<video>` and `<audio>`). `drop_element` writes nothing. With either of the last two, a real address on the element (a lazy-load attribute, a `srcset` candidate, a nested `<source>`, a `<source>` of the `<picture>` around an `<img>`) wins over the `data:` one, and a link whose only content was removed goes with it. A link whose own address is a `data:` URL gets the same choice: both `alt_text_only` and `drop_element` write the link’s text with no destination, since the link’s text is never dropped along with the address. The document structure follows the markdown. |
| `hidden_content` | `"drop"` \| `"reachable"` \| `"all"` | `"drop"` | Which text that a browser does not show at first the output holds. `drop` writes none of it. `reachable` keeps the text a reader can get to in the page: an element with the `hidden` attribute or with inline `display: none`, `visibility: hidden` or `font-size: 0` (an inactive tab panel, a collapsed section), and a declarative shadow root (a `<template>` whose `shadowrootmode` is `open` or `closed`). `all` also keeps the content of `<template>` and `<noscript>`, but not in the document head, where the two elements hold metadata. No choice writes a `<script>`, a `<style>` or a comment. The converter reads the inline `style` attribute only, so an element hidden by a style sheet rule or a class name is kept with every choice. |
| `max_image_size` | `int` (bytes) | `5242880` | Maximum byte size for an extracted inline image. Larger images are skipped. 5 MB default. |
| `capture_svg` | `bool` | `false` | Include inline `<svg>` elements in `result.images` when `extract_images` is enabled. |
| `infer_dimensions` | `bool` | `true` | Infer missing `width` and `height` from decoded image bytes when extracting inline images. |
### Tables
[Section titled “Tables”](#tables)
| Option | Type | Default | Description |
| ---------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `br_in_tables` | `bool` | `false` | Preserve line breaks in table cells as `<br>` rather than converting to spaces. |
| `compact_tables` | `bool` | `false` | Emit tables without column padding (no aligned widths, `---` separator per column). Token-efficient output for RAG / LLM contexts. |
### Whitespace
[Section titled “Whitespace”](#whitespace)
| Option | Type | Default | Description |
| ----------------- | ---------------------------- | -------------- | --------------------------------------------------------------------------------- |
| `whitespace_mode` | `"normalized"` \| `"strict"` | `"normalized"` | `normalized` cleans excess whitespace; `strict` preserves whitespace as-is. |
| `strip_newlines` | `bool` | `false` | Remove all newlines from input HTML before processing (useful for minified HTML). |
### Wrapping
[Section titled “Wrapping”](#wrapping)
| Option | Type | Default | Description |
| ------------ | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `wrap` | `bool` | `false` | Enable line wrapping. |
| `wrap_width` | `int` | `80` | Column width for line wrapping when `wrap` is enabled. Not range-checked by the core library; a value of `0` behaves as unlimited. |
### Element Handling
[Section titled “Element Handling”](#element-handling)
| Option | Type | Default | Description |
| ------------------- | ------- | ------- | --------------------------------------------------------------------------------------------- |
| `convert_as_inline` | `bool` | `false` | Treat block-level elements as inline (no paragraph breaks). |
| `strip_tags` | `array` | `[]` | Tags to strip entirely (only text content is preserved, no Markdown conversion). |
| `preserve_tags` | `array` | `[]` | Tags to emit verbatim as HTML instead of converting to Markdown. Counterpart to `strip_tags`. |
### Advanced
[Section titled “Advanced”](#advanced)
| Option | Type | Default | Description |
| ------------------- | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_depth` | `int` \| `null` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit (64). Values above the limit are clamped to an absolute ceiling (1024) to guard against stack overflow on pathologically deep input; there is no way to disable the depth limit entirely. |
| `exclude_selectors` | `array` | `[]` | CSS selectors for elements to drop entirely, including all descendants (unlike `strip_tags`, which keeps the text content). A selector matches an element by a tag name, `.class`, `#id`, an attribute (`[attr]`, `[attr=value]`), `*`, or these joined with no space (`div.note`). A selector with a combinator (`.menu a`, `div > p`, `h2 + p`) or a pseudo-class (`li:first-child`) matches nothing and reports no error. Invalid selectors are silently skipped at conversion time. |
| `tier_strategy` | `"auto"` \| `"tier2"` | `"auto"` | Which internal conversion path to use. `auto` runs a fast byte-scanner (Tier 1) when eligible and falls back to the full DOM walk (Tier 2) otherwise. `tier2` always uses the DOM-walk path. Not exposed as a stable option in every binding. |
Conversion output is not sanitized. There is no configurable cap on input size — callers that accept HTML from untrusted sources are responsible for enforcing their own size limits before calling `convert()`. See [Security](https://github.com/xberg-io/html-to-markdown/blob/main/SECURITY.md).
### Parsing
[Section titled “Parsing”](#parsing)
| Option | Type | Default | Description |
| ---------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `encoding` | `string` | `"utf-8"` | **CLI only.** Character encoding of the input file or stdin. The value must be a label that the WHATWG Encoding Standard recognises (`"windows-1252"`, `"shift_jis"`, `"iso-8859-1"`, etc.). The core library stores but does not use this field; decoding happens in the CLI before the string reaches `convert()`. |
### Debugging
[Section titled “Debugging”](#debugging)
| Option | Type | Default | Description |
| ------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `debug` | `bool` | `false` | **CLI only.** When true, the CLI prints diagnostic lines to stderr after each conversion (e.g. `"Generated 1234 bytes of markdown"`). The core library stores but does not act on this field. |
### Metadata Extraction
[Section titled “Metadata Extraction”](#metadata-extraction)
| Option | Type | Default | Description |
| ------------------ | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `extract_metadata` | `bool` | `true` | Populate `result.metadata` (title, description, Open Graph, Twitter Card, JSON-LD, links, images). Table extraction into `result.tables` runs unconditionally — it is not gated by this flag. |
### Document Structure
[Section titled “Document Structure”](#document-structure)
| Option | Type | Default | Description |
| ---------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------- |
| `include_document_structure` | `bool` | `false` | Populate `result.document` with a parsed tree of headings, paragraphs, lists, and tables. |
### Preprocessing
[Section titled “Preprocessing”](#preprocessing)
`preprocessing` is a nested `PreprocessingOptions` value (Rust field names shown below; bindings expose the same sub-fields as keyword arguments or a nested object). The CLI uses different flag names for the same settings (`--preprocess`, `--keep-navigation`, `--keep-forms`) — those CLI-only names do not exist on `ConversionOptions`; see [CLI Reference](/cli/).
| Option | Type | Default | Description |
| ------------------- | --------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | `bool` | `true` | Enable HTML preprocessing globally. Required for the options below to have an effect. |
| `preset` | `"minimal"` \| `"standard"` \| `"aggressive"` | `"standard"` | Preset level carried through for forward compatibility. Current releases honour the boolean flags below and do not branch on preset. |
| `remove_navigation` | `bool` | `true` | Remove `<nav>`, and remove `<header>`/`<footer>`/`<aside>` that otherwise look like navigation. |
| `remove_forms` | `bool` | `true` | Accepted and stored. Current releases do not drop form elements during preprocessing regardless of this flag. |
When `enabled` is `true` and `remove_navigation` is `true` (the default for both), the preprocessor drops:
* every `<nav>` element
* `<header>` elements outside a semantic content ancestor (`<article>`, `<main>`, etc.)
* `<header>`, `<footer>`, and `<aside>` that carry navigation hints in their class or id attributes (`menu`, `sidebar`, `breadcrumb`, and similar)
Script and style tags are always stripped before the DOM walk starts, independent of `enabled`.
## Output Format Comparison
[Section titled “Output Format Comparison”](#output-format-comparison)
Given this HTML:
```html
<h1>Report</h1>
<p>
See <a href="https://example.com"><strong>example</strong></a
>.
</p>
```
* markdown
```markdown
# Report
See [**example**](https://example.com).
```
* djot
```text
# Report
See [*example*](https://example.com).
```
* plain
```text
Report
See example.
```
`markdown` and `djot` both preserve structure and link targets. `djot` uses single-asterisk strong emphasis; `markdown` uses double asterisks. `plain` strips all formatting, link targets, and list markers, returning readable text only.
## Builder Examples
[Section titled “Builder Examples”](#builder-examples)
* Rust
```rust
use html_to_markdown_rs::{convert, CodeBlockStyle, ConversionOptions, HeadingStyle};
let options = ConversionOptions::builder()
.heading_style(HeadingStyle::Atx)
.code_block_style(CodeBlockStyle::Backticks)
.wrap(true)
.wrap_width(80)
.extract_metadata(true)
.build();
let result = convert(html, Some(options))?;
```
* Python
```python
from html_to_markdown import ConversionOptions, convert
options = ConversionOptions(
heading_style="atx",
code_block_style="backticks",
wrap=True,
wrap_width=80,
extract_metadata=True,
)
result = convert(html, options)
```
* TypeScript
```typescript
import { convert, ConversionOptions, HeadingStyle, CodeBlockStyle } from '@xberg-io/html-to-markdown';
const options: ConversionOptions = {
headingStyle: HeadingStyle.Atx,
codeBlockStyle: CodeBlockStyle.Backticks,
wrap: true,
wrapWidth: 80,
extractMetadata: true,
};
const result = convert(html, options);
```
* Go
```go
wrapWidth := uint(80)
extractMetadata := true
opts := htmltomarkdown.ConversionOptions{
HeadingStyle: htmltomarkdown.HeadingStyleAtx,
CodeBlockStyle: htmltomarkdown.CodeBlockStyleBackticks,
Wrap: true,
WrapWidth: &wrapWidth,
ExtractMetadata: &extractMetadata,
}
result, err := htmltomarkdown.Convert(html, &opts)
```
* Ruby
```ruby
result = HtmlToMarkdown.convert(
html,
heading_style: :atx,
code_block_style: :backticks,
wrap: true,
wrap_width: 80,
extract_metadata: true,
)
```
* PHP
```php
$options = ConversionOptions::from_json(json_encode([
'headingStyle' => 'Atx',
'codeBlockStyle' => 'Backticks',
'wrap' => true,
'wrapWidth' => 80,
'extractMetadata' => true,
]));
$result = HtmlToMarkdownApi::convert($html, $options);
```
* Java
```java
ConversionOptions options = ConversionOptions.builder()
.withHeadingStyle(HeadingStyle.Atx)
.withCodeBlockStyle(CodeBlockStyle.Backticks)
.withWrap(true)
.withWrapWidth(80)
.withExtractMetadata(true)
.build();
ConversionResult result = HtmlToMarkdown.convert(html, options);
```
* C#
```csharp
var options = new ConversionOptions
{
HeadingStyle = HeadingStyle.Atx,
CodeBlockStyle = CodeBlockStyle.Backticks,
Wrap = true,
WrapWidth = 80,
ExtractMetadata = true,
};
var result = HtmlToMarkdownConverter.Convert(html, options);
```
* Elixir
```elixir
opts = %HtmlToMarkdown.ConversionOptions{
heading_style: :atx,
code_block_style: :backticks,
wrap: true,
wrap_width: 80,
extract_metadata: true,
}
{:ok, result} = HtmlToMarkdown.convert(html, opts)
```
* R
```r
opts <- conversion_options(
heading_style = "Atx",
code_block_style = "Backticks",
wrap = TRUE,
wrap_width = 80L,
extract_metadata = TRUE
)
result <- convert(html, opts)
```
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Contributing
Thanks for considering a contribution to html-to-markdown. Every fix, feature, and documentation improvement helps.
## Ways to contribute
[Section titled “Ways to contribute”](#ways-to-contribute)
* **Report a bug** — [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=bug) with a minimal reproduction
* **Fix a bug** — look for issues tagged [`good first issue`](https://github.com/xberg-io/html-to-markdown/issues?q=label%3A%22good+first+issue%22) or [`help wanted`](https://github.com/xberg-io/html-to-markdown/issues?q=label%3A%22help+wanted%22)
* **Improve the docs** — edit any page directly on GitHub using the pencil icon, or clone and run the site locally
* **Add a feature** — open an issue first to discuss scope before writing code; large changes without prior discussion may not be accepted
## Getting started
[Section titled “Getting started”](#getting-started)
```bash
git clone https://github.com/xberg-io/html-to-markdown.git
cd html-to-markdown
task setup # installs deps, builds Rust extension, wires commit hooks
task test # should pass before you make any changes
```
Full prerequisites and per-language build instructions are in [`CONTRIBUTING.md`](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) at the repo root.
## Workflow
[Section titled “Workflow”](#workflow)
1. Fork the repo and create a branch: `git checkout -b fix/your-change`
2. Make your change, add tests if applicable
3. Run `task test` (Rust + Python) and `pnpm test` (JS/TS) as needed
4. Commit using [Conventional Commits](https://www.conventionalcommits.org/) — prek enforces this automatically
5. Push and open a pull request against `main`
## Documentation changes
[Section titled “Documentation changes”](#documentation-changes)
The docs site lives in `docs/` and builds with Zensical:
```bash
uv sync --group doc
uv run --no-sync zensical serve # live preview at localhost:8000
scripts/ci/docs/build.sh --strict # what CI runs — fix all warnings before pushing
```
New pages go in `docs/`, must be added to `nav:` in `mkdocs.yaml`, and should follow the style already on the page you’re editing: terse, table-driven.
## Getting help
[Section titled “Getting help”](#getting-help)
* **Join Our community** — [Discord](https://discord.gg/xt9WY3GnKR)
* **Report a Bugs** — [GitHub Issues](https://github.com/xberg-io/html-to-markdown/issues)
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Xberg.io
html-to-markdown is a high-performance, CommonMark-compliant HTML → Markdown converter. It’s part of the xberg.io ecosystem — a set of open-source tools from the same team, each built on a fast Rust core. Explore the related projects:
* **[Xberg](https://github.com/xberg-io/xberg)** — the open-source content-intelligence engine: text, tables, and metadata from 101 formats (115 file extensions), with OCR, transcription, and code intelligence. MIT.
* **[Xberg Pro](https://xberg.io)** — a complete self-hosted content-intelligence backend in a single container. Commercial.
* **[Xberg Enterprise](https://xberg.io)** — the distributed, governed content-intelligence platform, scaled on Kubernetes with team governance and support. Commercial.
* **[crawlberg](https://github.com/xberg-io/crawlberg)** — web crawling and scraping with HTML→Markdown and headless-Chrome fallback.
* **[liter-llm](https://github.com/xberg-io/liter-llm)** — universal LLM API client with native bindings for 14 languages and 165 providers.
* **[tree-sitter-language-pack](https://github.com/xberg-io/tree-sitter-language-pack)** — tree-sitter grammars and code-intelligence primitives.
* **[alef](https://github.com/xberg-io/alef)** — the polyglot binding generator that produces every per-language binding across the 5 polyglot repos.
# Error Handling
`convert()` returns `Result<ConversionResult, ConversionError>` in Rust. Every other binding maps the error to its native idiom: Python raises an exception, Go returns `(result, error)`, Java throws a checked exception, and so on.
Non-fatal issues never produce an error. They accumulate in `result.warnings` and the call still succeeds.
## ConversionError Variants
[Section titled “ConversionError Variants”](#conversionerror-variants)
Eight variants. All carry a `String` message except `IoError`, which wraps `std::io::Error` via `#[from]`.
| Variant | Payload | Cause |
| ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseError` | `String` | Malformed HTML the parser could not recover from. |
| `SanitizationError` | `String` | Reserved for binding use. The core library never constructs this variant today — there is no sanitization pass; `convert()` does not reject or clean unsafe markup. |
| `ConfigError` | `String` | `ConversionOptions` contains an invalid combination (unknown format string, out-of-range width, etc.). |
| `IoError` | `std::io::Error` | Reading a file, reading stdin, or writing output failed. |
| `Panic` | `String` | A panic was caught inside the conversion core. The FFI boundaries catch unwinds so other bindings see a normal error instead of a crash. |
| `InvalidInput` | `String` | Binary/corrupted data detected (compressed data, excess NUL or control bytes, undeclared UTF-16), or decoding failure for a wrong `encoding` setting. There is no input size cap — see [Security](https://github.com/xberg-io/html-to-markdown/blob/main/SECURITY.md). |
| `Visitor` | `String` | A visitor callback returned `VisitResult::Error(...)`. Only compiled with `features = ["visitor"]`. Rust users on default features never see this variant. |
| `Other` | `String` | Catch-all for anything that does not fit above. |
## Warnings
[Section titled “Warnings”](#warnings)
`result.warnings` is a `Vec<ProcessingWarning>`. Each warning has a kind and a message. The CLI prints them to stderr with `--show-warnings`; in library code, iterate and log them yourself.
Warnings are the right place to surface “this was weird but the conversion worked” signals: skipped oversized images, unknown class attributes on code blocks, malformed table rows that were repaired. None of these halt the call.
## Handling Patterns
[Section titled “Handling Patterns”](#handling-patterns)
* Rust
```rust
use html_to_markdown_rs::convert;
use html_to_markdown_rs::error::ConversionError;
fn main() {
// Binary data (detected via magic bytes) is rejected before parsing.
let html = "%PDF-1.4 not actually HTML";
match convert(html, None) {
Ok(result) => println!("{}", result.content.unwrap_or_default()),
Err(ConversionError::InvalidInput(message)) => {
eprintln!("invalid input: {message}");
}
Err(ConversionError::ParseError(message)) => {
eprintln!("parse error: {message}");
}
Err(other) => eprintln!("conversion failed: {other}"),
}
}
```
* Python
```python
from html_to_markdown import convert
from html_to_markdown.exceptions import InvalidInputError
# Binary data (detected via magic bytes) is rejected before parsing.
html = "%PDF-1.4 not actually HTML"
try:
result = convert(html)
markdown = result.content
except InvalidInputError as error:
print(f"invalid input: {error}")
```
* TypeScript
```typescript
import { convert } from "@xberg-io/html-to-markdown";
// Binary data (detected via magic bytes) is rejected before parsing.
const html = "%PDF-1.4 not actually HTML";
try {
const result = convert(html);
console.log(result.content ?? "");
} catch (error) {
// The native binding surfaces conversion failures as a standard Error.
console.error("conversion failed:", (error as Error).message);
}
```
* Go
```go
package main
import (
"fmt"
htmltomarkdown "github.com/xberg-io/html-to-markdown/packages/go/v3"
)
func main() {
// Binary data (detected via magic bytes) is rejected before parsing.
html := "%PDF-1.4 not actually HTML"
result, err := htmltomarkdown.Convert(html, nil)
if err != nil {
// Convert wraps the FFI error as "[<code>] <message>".
fmt.Println("conversion failed:", err)
return
}
if result.Content != nil {
fmt.Println(*result.Content)
}
}
```
* Ruby
```ruby
require 'html_to_markdown'
# Binary data (detected via magic bytes) is rejected before parsing.
html = "%PDF-1.4 not actually HTML"
begin
result = HtmlToMarkdown.convert(html)
markdown = result.content
rescue RuntimeError => e
# Native conversion failures surface as RuntimeError with the Rust error message.
warn "conversion failed: #{e.message}"
end
```
* PHP
```php
use HtmlToMarkdown\HtmlToMarkdownApi;
// Binary data (detected via magic bytes) is rejected before parsing.
$html = '%PDF-1.4 not actually HTML';
try {
$result = HtmlToMarkdownApi::convert($html);
echo $result->content;
} catch (\Exception $e) {
// Native conversion failures surface as \Exception, prefixed with the
// Rust error variant, e.g. "[InvalidInput] Invalid input: ...".
fwrite(STDERR, 'conversion failed: ' . $e->getMessage() . "\n");
}
```
* Java
```java
import io.xberg.htmltomarkdown.HtmlToMarkdown;
import io.xberg.htmltomarkdown.ConversionResult;
import io.xberg.htmltomarkdown.InvalidInputException;
import io.xberg.htmltomarkdown.HtmlToMarkdownRsException;
public class Example {
public static void main(String[] args) {
// Binary data (detected via magic bytes) is rejected before parsing.
String html = "%PDF-1.4 not actually HTML";
try {
ConversionResult result = HtmlToMarkdown.convert(html);
System.out.println(result.content());
} catch (InvalidInputException e) {
System.err.println("invalid input: " + e.getMessage());
} catch (HtmlToMarkdownRsException e) {
System.err.println("conversion failed: " + e.getMessage());
}
}
}
```
* C#
```csharp
using HtmlToMarkdown;
// Binary data (detected via magic bytes) is rejected before parsing.
var html = "%PDF-1.4 not actually HTML";
try
{
var result = HtmlToMarkdownConverter.Convert(html, null);
Console.WriteLine(result.Content);
}
catch (InvalidInputException e)
{
Console.Error.WriteLine($"invalid input: {e.Message}");
}
catch (ConversionErrorException e)
{
Console.Error.WriteLine($"conversion failed: {e.Message}");
}
```
* Elixir
```elixir
# Binary data (detected via magic bytes) is rejected before parsing.
html = "%PDF-1.4 not actually HTML"
case HtmlToMarkdown.convert(html) do
{:ok, result} ->
IO.puts(result.content)
{:error, message} ->
IO.puts(:stderr, "conversion failed: #{message}")
end
```
* R
```r
library(htmltomarkdown)
# Binary data (detected via magic bytes) is rejected before parsing.
html <- "%PDF-1.4 not actually HTML"
result <- tryCatch(
convert(html),
error = function(e) {
message("conversion failed: ", conditionMessage(e))
NULL
}
)
if (!is.null(result)) {
cat(result$content)
}
```
* C
```c
#include "html_to_markdown.h"
#include <stdio.h>
int main(void) {
/* Binary data (detected via magic bytes) is rejected before parsing. */
HTMAlefHandle result = htm_convert("%PDF-1.4 not actually HTML", 0);
if (result == 0) {
fprintf(stderr, "convert failed (code %d): %s\n",
htm_last_error_code(), htm_last_error_context());
return 1;
}
char *content = htm_conversion_result_content(result);
if (content != NULL) {
printf("%s\n", content);
htm_free_string(content);
}
htm_conversion_result_free(result);
return 0;
}
```
* Swift
```swift
import HtmlToMarkdown
do {
let result = try convert(html: "<h1>Hello</h1>")
print(result.content ?? "")
} catch let ConversionError.parseError(message, _) {
print("Parse failed: \(message)")
} catch let error as ConversionError {
print("Conversion failed: \(error)")
}
```
* Dart
```dart
import 'package:h2m/h2m.dart';
import 'package:h2m/src/html_to_markdown_rs_bridge_generated/frb_generated.dart'
show RustLib;
Future<void> main() async {
await RustLib.init();
try {
final result = await H2mBridge.convert('<h1>Hello</h1>');
print(result.content);
} catch (error) {
// ConversionError variants surface via flutter_rust_bridge as thrown errors.
print('Conversion failed: $error');
}
}
```
* Kotlin Android
```kotlin
import io.xberg.android.HtmlToMarkdown
import io.xberg.android.HtmlToMarkdownRsBridgeException
fun main() {
try {
val result = HtmlToMarkdown.convert("<h1>Hello</h1>")
println(result.content)
} catch (error: HtmlToMarkdownRsBridgeException) {
System.err.println("Conversion failed: ${error.message}")
}
}
```
* Zig
```zig
const std = @import("std");
const html_to_markdown = @import("html_to_markdown_rs");
pub fn main() !void {
const result_json = html_to_markdown.convert("<h1>Hello</h1>", null) catch |err| switch (err) {
html_to_markdown.ConversionError.ParseError => {
std.debug.print("Parse failed\n", .{});
return;
},
else => return err,
};
defer std.heap.c_allocator.free(result_json);
std.debug.print("{s}\n", .{result_json});
}
```
## CLI Warnings
[Section titled “CLI Warnings”](#cli-warnings)
The CLI hides warnings by default. Pass `--show-warnings` to print each one to stderr in the format `Warning [<kind>]: <message>`. The flag works with or without `--json`. See [CLI: JSON Output](/cli/#json-output).
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# AI Coding Assistants
Give your coding agent working knowledge of html-to-markdown so it writes correct `convert()` calls, picks the right options, and reaches for the right binding — without you pasting docs into the chat.
## What this plugin does
[Section titled “What this plugin does”](#what-this-plugin-does)
The plugin packages html-to-markdown’s usage patterns, options, and per-language APIs as agent skills. Once installed, your assistant can answer html-to-markdown questions and generate accurate code straight from your editor or terminal. It installs from this repo’s own [`xberg-io/html-to-markdown`](https://github.com/xberg-io/html-to-markdown) marketplace ; choose a runtime below.
## Install as a plugin
[Section titled “Install as a plugin”](#install-as-a-plugin)
**Claude Code**
```text
/plugin marketplace add xberg-io/html-to-markdown
/plugin install html-to-markdown@html-to-markdown
```
**Codex CLI**
```text
/plugins add https://github.com/xberg-io/html-to-markdown
```
Then search for `html-to-markdown` and select **Install Plugin**.
**Cursor**
Settings → Plugins → Add from URL → `https://github.com/xberg-io/html-to-markdown`, then select **html-to-markdown**.
**Gemini CLI**
From a checkout of this repository:
```sh
gemini extensions install ./plugin
```
The manifest is inside `plugin/`. See the [Gemini extension reference](https://geminicli.com/docs/extensions/reference/) for local installation and updates.
**Kimi installation and compatibility**
From a checkout of this repository, install with the Python Kimi CLI version used for native plugin validation:
```sh
uvx --from kimi-cli==1.51.0 kimi plugin install ./plugin
```
Native plugin installation was validated with Python Kimi CLI 1.51.0. The replacement `@moonshot-ai/kimi-code` 2.1.1 does not provide a `plugin` CLI subcommand; its interactive plugin loading has not been verified. These results do not establish compatibility with newer Kimi releases.
**Factory Droid**
```text
droid plugin marketplace add https://github.com/xberg-io/html-to-markdown
droid plugin install html-to-markdown@html-to-markdown
```
**GitHub Copilot CLI**
```text
copilot plugin marketplace add https://github.com/xberg-io/html-to-markdown
copilot plugin install html-to-markdown@html-to-markdown
```
**Pi**
From a checkout of this repository:
```bash
pi install ./plugin
```
After the next plugin release, install the same package used by OpenCode:
```bash
pi install npm:@xberg-io/opencode-html-to-markdown
```
Pi loads the bundled skills and prompt templates. Use `/html-to-markdown-convert` or `/html-to-markdown-metadata` with the input as arguments. Install the `html-to-markdown` CLI separately for shell access. This package does not register MCP servers, hooks, or native Pi extensions.
**opencode**
Add the package to `opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@xberg-io/opencode-html-to-markdown"]
}
```
## Install as an MCP server
[Section titled “Install as an MCP server”](#install-as-an-mcp-server)
The MCP-capable integrations above bundle the html-to-markdown MCP server and register it for you. Pi uses skills and CLI access instead. To wire the same server into any other MCP client directly, point it at the published CLI — no plugin required:
```json
{
"mcpServers": {
"html-to-markdown": {
"command": "npx",
"args": ["-y", "@xberg-io/html-to-markdown-cli@latest", "mcp"]
}
}
}
```
Python users can launch it through `uvx` instead:
```json
{
"mcpServers": {
"html-to-markdown": {
"command": "uvx",
"args": ["--from", "html-to-markdown-cli", "html-to-markdown", "mcp"]
}
}
}
```
The server exposes `convert_html` and `extract_metadata` — see the [MCP Reference](/reference/mcp/) for the full tool and parameter schema.
For the Hermes Python agent framework, install the plugin as a package instead:
```bash
pip install html-to-markdown-hermes-plugin
```
## Runtime resources and prerequisites
[Section titled “Runtime resources and prerequisites”](#runtime-resources-and-prerequisites)
The generated bundle targets Claude Code, Codex, Cursor, Gemini CLI, Kimi, OpenCode, Factory Droid, Hermes, Pi, Agent Plugins and GitHub Copilot CLI. Use [the plugin installation guide](https://github.com/xberg-io/html-to-markdown/blob/main/plugin/README.md) for the runtime’s installation method and configuration.
| Runtime | Integration |
| ------------------------------ | ---------------------------------------------------------------------- |
| Claude, Codex, Cursor, Factory | Native plugin manifests, skills and MCP configuration |
| Gemini CLI | Extension manifest, command templates and MCP configuration |
| Kimi | Plugin manifest and session instructions |
| OpenCode | npm adapter, instructions and MCP configuration |
| Hermes | Python plugin, explicitly selected skills and a local stdio MCP bridge |
| Pi | Skills and prompt templates; execute operations through the CLI |
| Agent Plugins, Copilot | Agent Plugins 1.0 manifest, skills and MCP configuration |
Install the product CLI before using Hermes or Pi. Hermes starts the installed CLI directly; its wheel does not include the auto-installing launcher used by other MCP clients. Select `list_tools` through the product’s Hermes bridge to inspect the supported tools and request schemas. Select skills explicitly when needed; they are not appended automatically to every conversation.
From a checkout, install the generated Hermes package into Hermes’ Python environment:
```sh
pip install ./plugin/.hermes/package
```
Enable the plugin in Hermes configuration. Loading project plugins also requires `HERMES_ENABLE_PROJECT_PLUGINS=true`. After a release publishes the updated package, the registry install is `pip install html-to-markdown-hermes-plugin`.
Pi resources can be installed from the checkout with `pi install ./plugin`. After a plugin release includes them, install `npm:@xberg-io/opencode-html-to-markdown` through Pi. Pi does not register an MCP server, hooks or executable extensions from this package.
## Standalone public skills
[Section titled “Standalone public skills”](#standalone-public-skills)
The [public skills directory](https://github.com/xberg-io/html-to-markdown/tree/main/skills) contains instructions you can install independently of the runtime plugin. Use the [skills CLI](https://github.com/vercel-labs/skills) to list and select them:
```sh
npx skills add xberg-io/html-to-markdown --list
npx skills add xberg-io/html-to-markdown
```
Choose the target agents interactively. For a local checkout, use `npx skills add ./skills`. This installs instructions; it does not install the product CLI, enable MCP, download models or set provider credentials.
# Installation
Install **html-to-markdown** for your language using the commands below. Each binding wraps the same Rust core, so behavior matches across runtimes. Pick a tab under **Language bindings** for copy-paste snippets, feature flags, and a quick verification step where applicable.
## Requirements
[Section titled “Requirements”](#requirements)
| Language | Min version | Package |
| -------------------- | ----------------- | ----------------------------------------------------- |
| Rust | 1.85 | `html-to-markdown-rs` on crates.io |
| Python | 3.10 | `html-to-markdown` on PyPI |
| TypeScript / Node.js | Node.js 18 | `@xberg-io/html-to-markdown` on npm |
| Go | 1.26 | `github.com/xberg-io/html-to-markdown/packages/go/v3` |
| Ruby | 3.2 | `html-to-markdown` on RubyGems |
| PHP | 8.2 | `xberg-io/html-to-markdown` on Packagist |
| Java | 25 | `io.xberg:html-to-markdown` on Maven Central |
| C# | .NET 10 | `XbergIo.HtmlToMarkdown` on NuGet |
| Elixir | 1.14 | `html_to_markdown` on Hex |
| R | 4.2 | `htmltomarkdown` on CRAN |
| C | — | `libhtml_to_markdown` (GitHub Releases) |
| WebAssembly | — | `@xberg-io/html-to-markdown-wasm` on npm |
| Swift | Swift 6.0 | `HtmlToMarkdown` SwiftPM package |
| Dart | 3.11 | `h2m` on pub.dev |
| Kotlin Android | Android minSdk 21 | `io.xberg:html-to-markdown-android` on Maven Central |
| Zig | 0.16 | `html_to_markdown_rs` Zig package |
***
## Language bindings
[Section titled “Language bindings”](#language-bindings)
* Rust
Add to `Cargo.toml`:
```toml
[dependencies]
html-to-markdown-rs = "3.6"
```
Or via `cargo add`:
```bash
cargo add html-to-markdown-rs
```
**Verify:**
```rust
use html_to_markdown_rs::convert;
fn main() {
let result = convert("<h1>Hello</h1>", None).unwrap();
println!("{}", result.content.unwrap());
// # Hello
}
```
### Feature flags
[Section titled “Feature flags”](#feature-flags)
By default only the `metadata` feature is enabled. Opt in to additional features as needed:
| Feature | Enables | Default | Availability |
| --------------- | --------------------------------------------------------------- | ------- | ----------------- |
| `metadata` | `HtmlMetadata` extraction and all `extract_*` options | yes | Available by v3.6 |
| `visitor` | `HtmlVisitor` trait and `ConversionError::Visitor` | no | Available by v3.6 |
| `inline-images` | data-URI decoding and inline SVG extraction | no | Available by v3.6 |
| `serde` | `Serialize`/`Deserialize` on all public option and result types | no | Available by v3.6 |
| `full` | all of the above | no | Available by v3.6 |
```toml
# With visitor support
html-to-markdown-rs = { version = "3.10", features = ["visitor"] }
# Everything
html-to-markdown-rs = { version = "3.10", features = ["full"] }
```
* Python
```bash
pip install html-to-markdown
```
Using `uv`:
```bash
uv add html-to-markdown
```
**Verify:**
```bash
python -c "from html_to_markdown import convert; print(convert('<h1>Hello</h1>').content)"
# # Hello
```
Requires Python 3.10+. The package ships precompiled wheels for Linux (x86_64, aarch64), macOS (Apple Silicon, x86_64), and Windows (x64). A source distribution is also available if no wheel matches your platform.
* TypeScript
```bash
pnpm add @xberg-io/html-to-markdown
```
Using `pnpm` or `yarn`:
```bash
pnpm add @xberg-io/html-to-markdown
yarn add @xberg-io/html-to-markdown
```
**Verify:**
```typescript
import { convert } from '@xberg-io/html-to-markdown';
const result = convert('<h1>Hello</h1>');
console.log(result.content);
// # Hello
```
Requires Node.js 18+. The package ships both ESM and CJS outputs with bundled TypeScript types. No separate `@types/` package needed.
* Go
```bash
go get github.com/xberg-io/html-to-markdown/packages/go/v3
```
**Verify:**
```go
package main
import (
"fmt"
htmltomarkdown "github.com/xberg-io/html-to-markdown/packages/go/v3"
)
func main() {
result, err := htmltomarkdown.Convert("<h1>Hello</h1>", nil)
if err != nil {
panic(err)
}
fmt.Println(*result.Content)
// # Hello
}
```
Requires Go 1.26+. The module bundles a precompiled `libhtml_to_markdown.a` static library for each supported platform — no separate Rust toolchain needed.
* Ruby
```bash
gem install html-to-markdown
```
Or add to your `Gemfile`:
```ruby
gem 'html-to-markdown', '~> 3.8'
```
**Verify:**
```bash
ruby -e "require 'html_to_markdown'; puts HtmlToMarkdown.convert('<h1>Hello</h1>').content"
# # Hello
```
Requires Ruby 3.2+. Precompiled native gems are available for Linux and macOS. On unsupported platforms `bundle install` will compile the extension from source, which requires a Rust toolchain.
* PHP
This is a native PHP extension (Rust `ext-php-rs`), installed with [PIE](https://github.com/php/pie) — not `composer require` (Composer cannot load a native extension):
```bash
pie install xberg-io/html-to-markdown
```
**Verify:**
```php
<?php
use HtmlToMarkdown\HtmlToMarkdownApi;
$result = HtmlToMarkdownApi::convert('<h1>Hello</h1>');
echo $result->content;
// # Hello
```
Requires PHP 8.2+. PIE downloads the prebuilt extension binary matching your PHP version and platform from the GitHub release (PHP 8.2–8.5 on Linux x86_64/arm64, macOS arm64, and Windows x86_64).
* Java
**Maven** — add to `pom.xml`:
```xml
<dependency>
<groupId>io.xberg</groupId>
<artifactId>html-to-markdown</artifactId>
<version>3.10.6</version>
</dependency>
```
**Gradle** — add to `build.gradle`:
```groovy
implementation 'io.xberg:html-to-markdown:3.10.6'
```
Or Kotlin DSL (`build.gradle.kts`):
```kotlin
implementation("io.xberg:html-to-markdown:3.10.6")
```
**Verify:**
```java
import io.xberg.htmltomarkdown.HtmlToMarkdown;
import io.xberg.htmltomarkdown.HtmlToMarkdownRsException;
public class Main {
public static void main(String[] args) throws HtmlToMarkdownRsException {
var result = HtmlToMarkdown.convert("<h1>Hello</h1>");
System.out.println(result.content());
// # Hello
}
}
```
Requires Java 25+. The JAR extracts the native `libhtml_to_markdown` shared library at startup. No separate install step is needed — the library is bundled for Linux x86_64, macOS arm64/x86_64, and Windows x64.
* C#
```bash
dotnet add package XbergIo.HtmlToMarkdown
```
Or via the NuGet Package Manager in Visual Studio — search for `XbergIo.HtmlToMarkdown`.
**Verify:**
```csharp
using HtmlToMarkdown;
var result = HtmlToMarkdownConverter.Convert("<h1>Hello</h1>", null);
Console.WriteLine(result.Content);
// # Hello
```
Targets .NET 10. The package bundles native binaries for Linux, macOS, and Windows via `NativeLibrary` P/Invoke.
* Elixir
Add to `mix.exs`:
```elixir
def deps do
[
{:html_to_markdown, "~> 3.8"}
]
end
```
Then fetch:
```bash
mix deps.get
```
**Verify:**
```elixir
{:ok, result} = HtmlToMarkdown.convert("<h1>Hello</h1>")
IO.puts(result.content)
# # Hello
```
Requires Elixir 1.14+. Uses Rustler NIFs — precompiled NIF binaries are fetched automatically via `RustlerPrecompiled`. Set `RUSTLER_PRECOMPILED_GLOBAL_CACHE_PATH` to control cache location.
* R
```r
install.packages("htmltomarkdown", repos = "https://xberg-io.r-universe.dev")
```
**Verify:**
```r
library(htmltomarkdown)
result <- htmltomarkdown::convert("<h1>Hello</h1>")
cat(result$content)
# # Hello
```
Requires R 4.2+. Available on CRAN for Linux (x86_64), macOS (arm64, x86_64), and Windows.
* C
Download a prebuilt release archive for your platform from the [GitHub Releases page](https://github.com/xberg-io/html-to-markdown/releases). Each archive contains:
* `libhtml_to_markdown.so` / `.dylib` / `.dll` — shared library
* `libhtml_to_markdown.a` — static library
* `html_to_markdown.h` — C header
**Build from source** (requires Rust toolchain):
```bash
git clone https://github.com/xberg-io/html-to-markdown.git
cd html-to-markdown
cargo build --release -p html-to-markdown-ffi
# output: target/release/libhtml_to_markdown.{so,dylib,dll}
```
**Link and verify:**
```c
#include "html_to_markdown.h"
#include <stdio.h>
int main(void) {
HTMAlefHandle result = htm_convert("<h1>Hello</h1>", 0);
if (result == 0) {
fprintf(stderr, "convert failed: %s\n", htm_last_error_context());
return 1;
}
char *content = htm_conversion_result_content(result);
if (content != NULL) {
printf("%s\n", content);
htm_free_string(content);
}
htm_conversion_result_free(result);
return 0;
}
```
Compile with:
```bash
gcc main.c -lhtml_to_markdown -L./target/release -o main
```
Every heap-allocated string returned across the FFI must be released with `htm_free_string`, and every result/options handle must be released with the matching `htm_*_free` function. The memory belongs to the Rust allocator — do not call `free()` directly.
* WASM
```bash
pnpm add @xberg-io/html-to-markdown-wasm
```
**Verify:**
```javascript
import { convert } from '@xberg-io/html-to-markdown-wasm';
const result = convert('<h1>Hello</h1>');
console.log(result.content);
// # Hello
```
The package’s default (Node.js) entry point loads the `.wasm` module synchronously — no `init()` call needed. Browser and bundler consumers import the `web`/`bundler` build instead, which exports an async `init()` function that must complete before the first `convert()` call. Works in browsers, Cloudflare Workers, Deno, and Bun.
* Swift
Add the package URL in SwiftPM:
```text
https://github.com/xberg-io/html-to-markdown
```
**Verify:**
```swift
import HtmlToMarkdown
let result = try convert(html: "<h1>Hello</h1>")
print(result.content()?.toString() ?? "")
```
Requires Swift 6.0+. The package currently targets macOS 13+ and iOS 16+.
* Dart
```bash
dart pub add h2m
```
**Verify:**
```dart
import 'package:h2m/h2m.dart';
import 'package:h2m/src/html_to_markdown_rs_bridge_generated/frb_generated.dart'
show RustLib;
await RustLib.init();
final result = await H2mBridge.convert('<h1>Hello</h1>');
print(result.content);
```
Requires Dart 3.11+. The generated package is pure Dart from the caller’s point of view and uses flutter_rust_bridge under the hood.
* Kotlin Android
Add the Android artifact:
```kotlin
implementation("io.xberg:html-to-markdown-android:3.10.6")
```
Requires Android minSdk 21. This is an Android AAR with bundled JNI libraries; Kotlin/JVM users should use the Java artifact (`io.xberg:html-to-markdown`) directly.
* Zig
Use the Zig package `html_to_markdown_rs` from the release artifacts or the repository package metadata.
```zig
const html_to_markdown = @import("html_to_markdown_rs");
```
Requires Zig 0.16+. The package wraps the generated C FFI library.
***
## Troubleshooting on Windows
[Section titled “Troubleshooting on Windows”](#troubleshooting-on-windows)
If `pip install html-to-markdown` fails on Windows 11 with Python 3.14 or later, try these steps:
1. **Force the prebuilt wheel:**
```bash
pip install --only-binary=:all: html-to-markdown
```
This prevents fallback to source build. If this fails, a wheel resolution issue exists — try updating `pip` or `uv`.
2. **Enable MSVC compiler (if sdist build is required):** Install Microsoft Visual Studio Build Tools with the “Desktop development with C++” workload. Then ensure MSVC’s `link.exe` precedes any GNU variants in `PATH`. Check with `where link` — the first result should be a path under `VC\Tools\MSVC`.
3. **Update pip or uv:** Python 3.14 wheel tags are recent. Run `pip install --upgrade pip` or `uv self update` to ensure correct wheel matching.
***
## CLI
[Section titled “CLI”](#cli)
Install via Cargo, or use [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) to grab the prebuilt binary from GitHub Releases:
```bash
cargo install html-to-markdown-cli
```
```bash
cargo binstall html-to-markdown-cli
```
Or via Homebrew:
Homebrew 6.0+ requires explicit trust for third-party taps. Trust once, then install:
```bash
brew trust xberg-io/tap
brew install xberg-io/tap/html-to-markdown
```
Or on Windows via [Scoop](https://scoop.sh):
```powershell
scoop bucket add xberg https://github.com/xberg-io/scoop-bucket
scoop install html-to-markdown
```
**Verify:**
```bash
echo "<h1>Hello</h1>" | html-to-markdown
# # Hello
```
See [CLI reference](/cli/) for all flags and options.
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Language Binding Guides
Every binding wraps the same Rust core. The option names and return shapes are identical across languages; only the syntax differs. This page covers per-language install notes and naming conventions.
## Rust
[Section titled “Rust”](#rust)
**Package:** `html-to-markdown-rs` on [crates.io](https://crates.io/crates/html-to-markdown-rs)
```toml
html-to-markdown-rs = "3.6"
```
Option structs follow Rust naming conventions (`snake_case`). Use the builder API via `ConversionOptions::builder()` or construct `ConversionOptions` directly.
See [Installation: Feature Flags](/installation/#feature-flags) for the five Cargo features.
## Python
[Section titled “Python”](#python)
**Package:** `html-to-markdown` on PyPI **Requires:** Python ≥ 3.10
```bash
pip install html-to-markdown
```
```python
from html_to_markdown import convert, ConversionOptions
result = convert("<h1>Title</h1>", ConversionOptions(heading_style="atx"))
print(result.content)
```
Option keys match the Rust field names (`snake_case`). `ConversionOptions` accepts keyword arguments. `ConversionResult` is a class with attributes — access fields as `result.content`, `result.metadata`, `result.tables`, `result.images`, `result.document`, `result.warnings`.
## TypeScript
[Section titled “TypeScript”](#typescript)
**Package:** `@xberg-io/html-to-markdown` on npm **Requires:** Node.js ≥ 18
```bash
pnpm add @xberg-io/html-to-markdown
```
```typescript
import { convert, HeadingStyle } from "@xberg-io/html-to-markdown";
const result = convert("<h1>Title</h1>", { headingStyle: HeadingStyle.Atx });
console.log(result.content);
```
Option keys are `camelCase` (`headingStyle`, `linkStyle`, `outputFormat`). The package ships both ESM and CJS outputs. TypeScript types are bundled.
## Go
[Section titled “Go”](#go)
**Module:** `github.com/xberg-io/html-to-markdown/packages/go/v3` **Requires:** Go ≥ 1.26
```bash
go get github.com/xberg-io/html-to-markdown/packages/go/v3
```
```go
import (
"fmt"
"log"
htmltomarkdown "github.com/xberg-io/html-to-markdown/packages/go/v3"
)
result, err := htmltomarkdown.Convert("<h1>Title</h1>", nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(*result.Content)
```
Options use Go struct field names (`PascalCase`). `Convert` returns `(*ConversionResult, error)`. Errors are standard Go errors. Use `errors.Is`/`errors.As` to inspect them.
## Ruby
[Section titled “Ruby”](#ruby)
**Gem:** `html-to-markdown` on RubyGems **Requires:** Ruby ≥ 3.2
```bash
gem install html-to-markdown
```
```ruby
require 'html_to_markdown'
result = HtmlToMarkdown.convert('<h1>Title</h1>', heading_style: :atx)
puts result.content
```
Options are keyword arguments with `snake_case` symbols. `result` is a `ConversionResult` object exposing accessor methods (`content`, `metadata`, `tables`, …), not a hash. Errors raise `HtmlToMarkdown::ConversionError`.
## PHP
[Section titled “PHP”](#php)
**Package:** `xberg-io/html-to-markdown` (native `ext-php-rs` extension) **Requires:** PHP ≥ 8.2
Install with [PIE](https://github.com/php/pie) — not `composer require`, which cannot load a native extension:
```bash
pie install xberg-io/html-to-markdown
```
```php
use HtmlToMarkdown\HtmlToMarkdownApi;
use HtmlToMarkdown\ConversionOptions;
$options = ConversionOptions::from_json(json_encode(['headingStyle' => 'Atx']));
$result = HtmlToMarkdownApi::convert('<h1>Title</h1>', $options);
echo $result->content;
```
Classes live in the flat `HtmlToMarkdown\` namespace. `HtmlToMarkdownApi::convert` returns a `ConversionResult` object: `$result->content` is a public property, while `$result->getMetadata()` and `$result->getTables()` are accessor methods. Conversion failures throw `HtmlToMarkdown\HtmlToMarkdownException`.
## Java
[Section titled “Java”](#java)
**Maven:** `io.xberg:html-to-markdown` **Requires:** Java ≥ 25
```xml
<dependency>
<groupId>io.xberg</groupId>
<artifactId>html-to-markdown</artifactId>
<version>3.6.8</version>
</dependency>
```
```java
import io.xberg.htmltomarkdown.HtmlToMarkdown;
import io.xberg.htmltomarkdown.ConversionOptions;
import io.xberg.htmltomarkdown.ConversionResult;
import io.xberg.htmltomarkdown.HeadingStyle;
import io.xberg.htmltomarkdown.HtmlToMarkdownRsException;
public class Main {
public static void main(String[] args) throws HtmlToMarkdownRsException {
ConversionOptions options = ConversionOptions.builder()
.withHeadingStyle(HeadingStyle.Atx)
.build();
ConversionResult result = HtmlToMarkdown.convert("<h1>Title</h1>", options);
System.out.println(result.content());
}
}
```
Uses a builder for options. Conversion failures throw `io.xberg.htmltomarkdown.HtmlToMarkdownRsException` and its subtypes (`ParseErrorException`, `ConfigErrorException`, `InvalidInputException`, `PanicException`, `OtherException`). Native binaries ship in the JAR for Linux x86_64, macOS arm64/x86_64, and Windows x86_64.
## C# (.NET)
[Section titled “C# (.NET)”](#c-net)
**NuGet:** `XbergIo.HtmlToMarkdown` **Requires:** .NET 10
```bash
dotnet add package XbergIo.HtmlToMarkdown
```
```csharp
using HtmlToMarkdown;
var options = new ConversionOptions { HeadingStyle = HeadingStyle.Atx };
var result = HtmlToMarkdownConverter.Convert("<h1>Title</h1>", options);
Console.WriteLine(result.Content);
```
Classes live in the `HtmlToMarkdown` namespace (the `XbergIo.HtmlToMarkdown` prefix is only the NuGet package id). Properties are `PascalCase`. Errors throw `HtmlToMarkdownRsException` and subtypes.
## Elixir
[Section titled “Elixir”](#elixir)
**Hex:** `html_to_markdown` **Requires:** Elixir ≥ 1.14
```elixir
{:html_to_markdown, "~> 3.8"}
```
```elixir
case HtmlToMarkdown.convert("<h1>Title</h1>", %{heading_style: :atx}) do
{:ok, result} -> IO.puts(result.content)
{:error, _kind, reason} -> IO.warn("failed: #{reason}")
end
```
`convert/2` returns `{:ok, result}` or `{:error, kind, reason}`. Options are a map or a `%HtmlToMarkdown.ConversionOptions{}` struct. The struct fields match the Rust names (`snake_case`).
## R
[Section titled “R”](#r)
**CRAN:** `htmltomarkdown` **Requires:** R ≥ 4.2
```r
install.packages("htmltomarkdown", repos = "https://xberg-io.r-universe.dev")
```
```r
library(htmltomarkdown)
result <- htmltomarkdown::convert("<h1>Title</h1>", heading_style = "atx")
cat(result$content)
```
Options are named function arguments. The returned list matches the `ConversionResult` shape with `snake_case` names. Errors stop execution with a message; wrap in `tryCatch` if you need to handle them.
## C
[Section titled “C”](#c)
**Link against:** `libhtml_to_markdown` **Header:** `html_to_markdown.h` (HTM\*H, all symbols prefixed `htm*_`/`HTM_`)
Download a pre-built release archive for your platform from the [GitHub releases page](https://github.com/xberg-io/html-to-markdown/releases), or build from source with `cargo build --release -p html-to-markdown-ffi`.
```c
#include "html_to_markdown.h"
HTMAlefHandle result = htm_convert("<h1>Title</h1>", 0);
if (result != 0) {
char *content = htm_conversion_result_content(result);
if (content != NULL) {
printf("%s\n", content);
htm_free_string(content);
}
htm_conversion_result_free(result);
}
```
Every heap-allocated string must be released with `htm_free_string` and every handle with the matching `htm_*_free` function. The C API is a thin synchronous FFI layer. No async mode, no thread-local state. Conversion errors return `0` and set the thread-local error accessible via `htm_last_error_code` / `htm_last_error_context`.
## WASM
[Section titled “WASM”](#wasm)
**npm:** `@xberg-io/html-to-markdown-wasm`
```bash
pnpm add @xberg-io/html-to-markdown-wasm
```
```javascript
import { convert, WasmConversionOptions, WasmHeadingStyle } from "@xberg-io/html-to-markdown-wasm";
const options = WasmConversionOptions.default();
options.headingStyle = WasmHeadingStyle.Atx;
const result = convert("<h1>Title</h1>", options);
console.log(result.content);
```
The package’s default (Node.js) entry point loads the `.wasm` module synchronously — no `init()` call needed. Browser and bundler consumers import the `web`/`bundler` build instead, which exports an async `init()` function that must complete before the first `convert()` call. `convert()` takes a `WasmConversionOptions` instance built via `WasmConversionOptions.default()`, not a plain object literal — its fields use `camelCase` and have the same shape as the TypeScript binding. The WASM build exposes inline image extraction when built with `inline-images`; generated native bindings may omit the Rust-only image payload.
## Swift
[Section titled “Swift”](#swift)
**Package:** `HtmlToMarkdown` via SwiftPM **Requires:** Swift ≥ 6.0
Add the package from `https://github.com/xberg-io/html-to-markdown` and import `HtmlToMarkdown`.
## Dart
[Section titled “Dart”](#dart)
**Package:** `h2m` on pub.dev **Requires:** Dart ≥ 3.11
```bash
dart pub add h2m
```
The package is pure Dart from the caller’s point of view and uses the generated flutter_rust_bridge runtime.
## Kotlin Android
[Section titled “Kotlin Android”](#kotlin-android)
**Package:** `io.xberg:html-to-markdown-android` **Requires:** Android minSdk 21
Kotlin Android is an AAR with bundled JNI libraries. Kotlin/JVM users should use the Java package (`io.xberg:html-to-markdown`) directly.
## Zig
[Section titled “Zig”](#zig)
**Package:** `html_to_markdown_rs` **Requires:** Zig ≥ 0.16
The Zig package wraps the C FFI surface and links to the generated native library.
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Migrating to v3
## Background
[Section titled “Background”](#background)
html-to-markdown began as a Python library — a fork of [markdownify](https://github.com/matthewwithanm/python-markdownify) — focused on converting HTML to Markdown. Over time, the core was rewritten in Rust for performance, and generated packages were added for 15 language surfaces: Python, TypeScript, Ruby, Go, PHP, Java, C#, Elixir, R, C, WebAssembly, Swift, Dart, Kotlin Android, and Zig.
v3.0.0 rationalises the library’s API surface. Instead of multiple specialised functions, there is now a single `convert()` function that returns a structured `ConversionResult`. This simplifies the API while making all extraction capabilities available through one call.
### hOCR support moved to Xberg
[Section titled “hOCR support moved to Xberg”](#hocr-support-moved-to-xberg)
hOCR (OCR-generated HTML) processing was removed from html-to-markdown and moved into [Xberg](https://github.com/xberg-io/xberg), the document extraction library in the Xberg ecosystem. hOCR is a document-level concern — it belongs in the extraction pipeline, not in an html-to-markdown converter.
## API changes
[Section titled “API changes”](#api-changes)
### Before (v2)
[Section titled “Before (v2)”](#before-v2)
v2 had multiple functions for different extraction needs:
* `convert(html)` → `String`
* `convert_with_metadata(html, options, config)` → `(String, Metadata)`
* `convert_with_inline_images(html, options, config)` → `Extraction`
* `convert_with_tables(html, options)` → `TablesResult`
* `convert_with_visitor(html, options, visitor)` → `String`
### After (v3)
[Section titled “After (v3)”](#after-v3)
v3 has one function:
* `convert(html, options?, visitor?)` → `ConversionResult`
`ConversionResult` contains all data:
* `content` — the converted text (Markdown, Djot, or plain text)
* `metadata` — HTML metadata (title, OG, links, images, structured data)
* `tables` — extracted tables with cell data
* `document` — structured document tree (when enabled)
* `images` — extracted inline images where the binding exposes them (Rust and WASM when built with inline image support; generated native bindings may omit the Rust-only image payload)
* `warnings` — non-fatal processing warnings
### Migration table
[Section titled “Migration table”](#migration-table)
| v2 | v3 |
| --------------------------------------------- | --------------------------------------------------------- |
| `convert(html)` | `convert(html).content` |
| `convert_with_metadata(html, opts, cfg)` | `convert(html, opts).metadata` |
| `convert_with_inline_images(html, opts, cfg)` | `convert(html, opts).images` (set `extract_images: true`) |
| `convert_with_tables(html, opts)` | `convert(html, opts).tables` |
| `convert_with_visitor(html, opts, v)` | `convert(html, opts, v).content` |
| `convert_to_string(html)` | `convert(html).content` |
| `hocr_spatial_tables: true` | Use [Xberg](https://github.com/xberg-io/xberg) |
| `ExtendedMetadata` | `HtmlMetadata` |
| `start_profiling()` | Removed |
| `markdownify(html)` (Python) | `convert(html).content` |
## Examples by language
[Section titled “Examples by language”](#examples-by-language)
### Rust
[Section titled “Rust”](#rust)
```rust
// v2
let markdown = convert(html, None)?;
let (md, meta) = convert_with_metadata(html, None, cfg, None)?;
// v3
let result = convert(html, None)?;
let markdown = result.content.unwrap_or_default();
let metadata = result.metadata; // always available
```
### Python
[Section titled “Python”](#python)
```python
# v2
markdown = convert(html)
markdown, metadata = convert_with_metadata(html)
# v3
result = convert(html)
markdown = result.content
metadata = result.metadata
```
### TypeScript
[Section titled “TypeScript”](#typescript)
```typescript
// v2
const markdown = convert(html);
const { markdown, metadata } = convertWithMetadata(html);
// v3
const result = convert(html);
const markdown = result.content;
const metadata = result.metadata;
```
### Go
[Section titled “Go”](#go)
```go
// v2
markdown, err := htmltomarkdown.Convert(html, nil)
markdown, meta, err := htmltomarkdown.ConvertWithMetadata(html, nil)
// v3
result, err := htmltomarkdown.Convert(html, nil)
markdown := result.Content
metadata := result.Metadata
```
### Ruby
[Section titled “Ruby”](#ruby)
```ruby
# v2
markdown = HtmlToMarkdown.convert(html)
markdown, metadata = HtmlToMarkdown.convert_with_metadata(html)
# v3
result = HtmlToMarkdown.convert(html)
markdown = result.content
metadata = result.metadata
```
### PHP
[Section titled “PHP”](#php)
```php
// v2
$markdown = HtmlToMarkdown\convert($html);
[$markdown, $metadata] = HtmlToMarkdown\convert_with_metadata($html);
// v3
$result = HtmlToMarkdown\HtmlToMarkdownApi::convert($html);
$markdown = $result->content;
$metadata = $result->getMetadata();
```
### Java
[Section titled “Java”](#java)
```java
// v2
String markdown = HtmlToMarkdown.convert(html);
ConversionPair pair = HtmlToMarkdown.convertWithMetadata(html);
// v3
ConversionResult result = HtmlToMarkdown.convert(html);
String markdown = result.content();
HtmlMetadata metadata = result.metadata();
```
### C# (.NET)
[Section titled “C# (.NET)”](#c-net)
```csharp
// v2
string markdown = HtmlToMarkdown.Convert(html);
(string md, Metadata meta) = HtmlToMarkdown.ConvertWithMetadata(html);
// v3
ConversionResult result = HtmlToMarkdownConverter.Convert(html, null);
string markdown = result.Content;
HtmlMetadata metadata = result.Metadata;
```
### Elixir
[Section titled “Elixir”](#elixir)
```elixir
# v2
{:ok, markdown} = HtmlToMarkdown.convert(html)
{:ok, markdown, metadata} = HtmlToMarkdown.convert_with_metadata(html)
# v3
{:ok, result} = HtmlToMarkdown.convert(html)
markdown = result.content
metadata = result.metadata
```
### R
[Section titled “R”](#r)
```r
# v2
markdown <- html_to_markdown(html)
result <- html_to_markdown_with_metadata(html)
# v3
result <- convert(html)
markdown <- result$content
metadata <- result$metadata
```
### C (FFI)
[Section titled “C (FFI)”](#c-ffi)
```c
/* v2 */
char *markdown = htm_convert(html, NULL);
htm_free(markdown);
/* v3 */
HTMAlefHandle result = htm_convert(html, 0);
char *markdown = htm_conversion_result_content(result);
htm_free_string(markdown);
htm_conversion_result_free(result);
```
## C ABI: handles replace pointers
[Section titled “C ABI: handles replace pointers”](#c-abi-handles-replace-pointers)
Separate from the v2 to v3 API change above, the C ABI itself changed. Objects no longer cross the boundary as opaque struct pointers. They are now `HTMAlefHandle`, a `uint64_t` handle into a registry owned by the library. The null handle is `0`, so comparisons against `NULL` on these types become comparisons against `0`.
Strings are unaffected: they are still `char *` and are still released with `htm_free_string`. The visitor callback struct `HTMHtmVisitorCallbacks` and the `HTM_VISIT_*` status codes are unchanged.
Only code that includes `html_to_markdown.h` and links the native library directly needs to change. The shipped language bindings are regenerated against the new ABI and their public APIs are the same.
```c
/* before */
HTMConversionOptions *options = htm_conversion_options_from_json("{}");
HTMConversionResult *result = htm_convert(html, options);
if (result == NULL) {
fprintf(stderr, "%s\n", htm_last_error_context());
return 1;
}
char *markdown = htm_conversion_result_content(result);
htm_free_string(markdown);
htm_conversion_result_free(result);
htm_conversion_options_free(options);
/* after */
HTMAlefHandle options = htm_conversion_options_from_json("{}");
HTMAlefHandle result = htm_convert(html, options);
if (result == 0) {
fprintf(stderr, "%s\n", htm_last_error_context());
return 1;
}
char *markdown = htm_conversion_result_content(result); /* unchanged: still char* */
htm_free_string(markdown);
htm_conversion_result_free(result);
htm_conversion_options_free(options);
```
Where you declared `T *`, declare `HTMAlefHandle`. Where you compared against `NULL`, compare against `0`. A bare truth test such as `if (result)` keeps working, because the null handle is zero.
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# C API Reference
## C API Reference v3.17.2
[Section titled “C API Reference v3.17.2”](#c-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### htm_convert()
[Section titled “htm_convert()”](#htm_convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```c
HTMAlefHandle htm_convert(const char* html, HTMAlefHandle options);
```
**Example:**
```c
HTMAlefHandle result = htm_convert("value", 0);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------- | -------- | ------------------ |
| `html` | `const char*` | Yes | The html |
| `options` | `HTMAlefHandle` | No | The options to use |
**Returns:** `HTMAlefHandle`
**Errors:** Returns the sentinel handle `0` on error.
***
### Types
[Section titled “Types”](#types)
#### HTMConversionOptions
[Section titled “HTMConversionOptions”](#htmconversionoptions)
**C representation:** `HTMConversionOptions` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMConversionOptions` does not appear anywhere in the generated header.
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ------------------------------ | --------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading_style` | `HTMAlefHandle` | `HTM_ATX` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `list_indent_type` | `HTMAlefHandle` | `HTM_SPACES` | How to indent nested list items (spaces or tab). |
| `list_indent_width` | `uintptr_t` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `const char*` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strong_em_symbol` | `const char*` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escape_asterisks` | `int32_t` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escape_underscores` | `int32_t` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escape_misc` | `int32_t` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escape_ascii` | `int32_t` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `code_language` | `const char*` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `int32_t` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expand_abbreviations` | `int32_t` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `include_blockquote_citations` | `int32_t` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `default_title` | `int32_t` | `false` | Emit a default title when no `<title>` tag is present. |
| `br_in_tables` | `int32_t` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compact_tables` | `int32_t` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlight_style` | `HTMAlefHandle` | `HTM_DOUBLE_EQUAL` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extract_metadata` | `int32_t` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespace_mode` | `HTMAlefHandle` | `HTM_NORMALIZED` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `strip_newlines` | `int32_t` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `int32_t` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrap_width` | `uintptr_t` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convert_as_inline` | `int32_t` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `sub_symbol` | `const char*` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `sup_symbol` | `const char*` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newline_style` | `HTMAlefHandle` | `HTM_SPACES` | How to encode hard line breaks (`<br>`) in Markdown. |
| `code_block_style` | `HTMAlefHandle` | `HTM_BACKTICKS` | Style used for fenced code blocks (backticks or tilde). |
| `keep_inline_images_in` | `const char*` | `NULL` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `HTMAlefHandle` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `const char*` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `int32_t` | `false` | Emit debug information during conversion. |
| `strip_tags` | `const char*` | `NULL` | HTML tag names whose content is stripped from the output entirely. |
| `preserve_tags` | `const char*` | `NULL` | HTML tag names that are preserved verbatim in the output. |
| `skip_images` | `int32_t` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inline_data_media` | `HTMAlefHandle` | `HTM_KEEP` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hidden_content` | `HTMAlefHandle` | `HTM_DROP` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `url_escape_style` | `HTMAlefHandle` | `HTM_ANGLE` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `link_style` | `HTMAlefHandle` | `HTM_INLINE` | Link rendering style (inline or reference). |
| `output_format` | `HTMAlefHandle` | `HTM_MARKDOWN` | Target output format (Markdown, plain text, etc.). |
| `include_document_structure` | `int32_t` | `false` | Include structured document tree in result. |
| `extract_images` | `int32_t` | `false` | Extract inline images from data URIs and SVGs. |
| `max_image_size` | `uint64_t` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `max_input_size` | `uint64_t*` | `NULL` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `NULL`. Set `Some(bytes)` to choose another limit or `NULL` to disable it. |
| `capture_svg` | `int32_t` | `false` | Capture SVG elements as images. |
| `infer_dimensions` | `int32_t` | `true` | Infer image dimensions from data. |
| `max_depth` | `uintptr_t*` | `NULL` | Maximum DOM traversal depth. `NULL` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `exclude_selectors` | `const char*` | `NULL` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tier_strategy` | `HTMAlefHandle` | `HTM_AUTO` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `base_url` | `const char*` | `NULL` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `NULL` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `HTMAlefHandle` | `NULL` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### HTMConversionResult
[Section titled “HTMConversionResult”](#htmconversionresult)
**C representation:** `HTMConversionResult` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMConversionResult` does not appear anywhere in the generated header.
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `const char*` | `NULL` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `HTMAlefHandle` | `NULL` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `NULL` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HTMAlefHandle` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `const char*` | `NULL` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `const char*` | `NULL` | Non-fatal processing warnings. |
***
#### HTMDocumentMetadata
[Section titled “HTMDocumentMetadata”](#htmdocumentmetadata)
**C representation:** `HTMDocumentMetadata` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMDocumentMetadata` does not appear anywhere in the generated header.
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| ---------------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `const char*` | `NULL` | Document title from `<title>` tag |
| `description` | `const char*` | `NULL` | Document description from `<meta name="description">` tag |
| `keywords` | `const char*` | `NULL` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `const char*` | `NULL` | Document author from `<meta name="author">` tag |
| `canonical_url` | `const char*` | `NULL` | Canonical URL from `<link rel="canonical">` tag |
| `base_href` | `const char*` | `NULL` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `const char*` | `NULL` | Document language from `lang` attribute |
| `text_direction` | `HTMAlefHandle` | `NULL` | Document text direction from `dir` attribute |
| `open_graph` | `const char*` | `NULL` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitter_card` | `const char*` | `NULL` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `meta_tags` | `const char*` | `NULL` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### HTMDocumentNode
[Section titled “HTMDocumentNode”](#htmdocumentnode)
**C representation:** `HTMDocumentNode` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMDocumentNode` does not appear anywhere in the generated header.
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | --------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `const char*` | — | Deterministic node identifier. |
| `content` | `HTMAlefHandle` | — | The semantic content of this node. |
| `parent` | `uint32_t*` | `NULL` | Index of the parent node (None for root nodes). |
| `children` | `const char*` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `const char*` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `const char*` | `NULL` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `NULL` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### HTMDocumentStructure
[Section titled “HTMDocumentStructure”](#htmdocumentstructure)
**C representation:** `HTMDocumentStructure` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMDocumentStructure` does not appear anywhere in the generated header.
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| --------------- | ------------- | ------- | --------------------------------------------------- |
| `nodes` | `const char*` | — | All nodes in document reading order. |
| `source_format` | `const char*` | `NULL` | The source format (always “html” for this library). |
***
#### HTMGridCell
[Section titled “HTMGridCell”](#htmgridcell)
**C representation:** `HTMGridCell` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMGridCell` does not appear anywhere in the generated header.
A single cell in a table grid.
| Field | Type | Default | Description |
| ----------- | ------------- | ---------------------- | ---------------------------------------------- |
| `content` | `const char*` | — | The text content of the cell. |
| `row` | `uint32_t` | — | 0-indexed row position. |
| `col` | `uint32_t` | — | 0-indexed column position. |
| `row_span` | `uint32_t` | `1` | Number of rows this cell spans (default 1). |
| `col_span` | `uint32_t` | `1` | Number of columns this cell spans (default 1). |
| `is_header` | `int32_t` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HTMHeaderMetadata
[Section titled “HTMHeaderMetadata”](#htmheadermetadata)
**C representation:** `HTMHeaderMetadata` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMHeaderMetadata` does not appear anywhere in the generated header.
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------- | ------------- | ------- | ----------------------------------------- |
| `level` | `uint8_t` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `const char*` | — | Normalized text content of the header |
| `id` | `const char*` | `NULL` | HTML id attribute if present |
| `depth` | `uintptr_t` | — | Document tree depth at the header element |
| `html_offset` | `uintptr_t` | — | Byte offset in original HTML document |
***
#### HTMHtmlMetadata
[Section titled “HTMHtmlMetadata”](#htmhtmlmetadata)
**C representation:** `HTMHtmlMetadata` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMHtmlMetadata` does not appear anywhere in the generated header.
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ----------------- | --------------- | ------- | ------------------------------------------------------------- |
| `document` | `HTMAlefHandle` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `const char*` | `NULL` | Extracted header elements with hierarchy |
| `links` | `const char*` | `NULL` | Extracted hyperlinks with type classification |
| `images` | `const char*` | `NULL` | Extracted images with source and dimensions |
| `structured_data` | `const char*` | `NULL` | Extracted structured data blocks |
***
#### HTMHtmlVisitor
[Section titled “HTMHtmlVisitor”](#htmhtmlvisitor)
**C representation:** `HTMHtmlVisitor` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMHtmlVisitor` does not appear anywhere in the generated header.
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### htm_html_visitor_visit_text()
[Section titled “htm_html_visitor_visit_text()”](#htm_html_visitor_visit_text)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_text(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_text(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_element_start()
[Section titled “htm_html_visitor_visit_element_start()”](#htm_html_visitor_visit_element_start)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_element_start(HTMAlefHandle this, HTMAlefHandle ctx);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_element_start(instance, 0);
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_element_end()
[Section titled “htm_html_visitor_visit_element_end()”](#htm_html_visitor_visit_element_end)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_element_end(HTMAlefHandle this, HTMAlefHandle ctx, const char* output);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_element_end(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `output` | `const char*` | Yes | The output |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_link()
[Section titled “htm_html_visitor_visit_link()”](#htm_html_visitor_visit_link)
Visit anchor links `<a href="...">`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_link(HTMAlefHandle this, HTMAlefHandle ctx, const char* href, const char* text, const char* title);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_link(instance, 0, "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `href` | `const char*` | Yes | The href |
| `text` | `const char*` | Yes | The text |
| `title` | `const char*` | No | The title |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_image()
[Section titled “htm_html_visitor_visit_image()”](#htm_html_visitor_visit_image)
Visit images `<img src="...">`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_image(HTMAlefHandle this, HTMAlefHandle ctx, const char* src, const char* alt, const char* title);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_image(instance, 0, "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `src` | `const char*` | Yes | The src |
| `alt` | `const char*` | Yes | The alt |
| `title` | `const char*` | No | The title |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_heading()
[Section titled “htm_html_visitor_visit_heading()”](#htm_html_visitor_visit_heading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_heading(HTMAlefHandle this, HTMAlefHandle ctx, uint32_t level, const char* text, const char* id);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_heading(instance, 0, 42, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `level` | `uint32_t` | Yes | The level |
| `text` | `const char*` | Yes | The text |
| `id` | `const char*` | No | The id |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_code_block()
[Section titled “htm_html_visitor_visit_code_block()”](#htm_html_visitor_visit_code_block)
Visit code blocks `<pre><code>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_code_block(HTMAlefHandle this, HTMAlefHandle ctx, const char* lang, const char* code);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_code_block(instance, 0, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `lang` | `const char*` | No | The lang |
| `code` | `const char*` | Yes | The code |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_code_inline()
[Section titled “htm_html_visitor_visit_code_inline()”](#htm_html_visitor_visit_code_inline)
Visit inline code `<code>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_code_inline(HTMAlefHandle this, HTMAlefHandle ctx, const char* code);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_code_inline(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `code` | `const char*` | Yes | The code |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_list_item()
[Section titled “htm_html_visitor_visit_list_item()”](#htm_html_visitor_visit_list_item)
Visit list items `<li>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_list_item(HTMAlefHandle this, HTMAlefHandle ctx, int32_t ordered, const char* marker, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_list_item(instance, 0, true, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `ordered` | `int32_t` | Yes | The ordered |
| `marker` | `const char*` | Yes | The marker |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_list_start()
[Section titled “htm_html_visitor_visit_list_start()”](#htm_html_visitor_visit_list_start)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_list_start(HTMAlefHandle this, HTMAlefHandle ctx, int32_t ordered);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_list_start(instance, 0, true);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `ordered` | `int32_t` | Yes | The ordered |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_list_end()
[Section titled “htm_html_visitor_visit_list_end()”](#htm_html_visitor_visit_list_end)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_list_end(HTMAlefHandle this, HTMAlefHandle ctx, int32_t ordered, const char* output);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_list_end(instance, 0, true, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `ordered` | `int32_t` | Yes | The ordered |
| `output` | `const char*` | Yes | The output |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_table_start()
[Section titled “htm_html_visitor_visit_table_start()”](#htm_html_visitor_visit_table_start)
Called before processing a table `<table>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_table_start(HTMAlefHandle this, HTMAlefHandle ctx);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_table_start(instance, 0);
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_table_row()
[Section titled “htm_html_visitor_visit_table_row()”](#htm_html_visitor_visit_table_row)
Visit table rows `<tr>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_table_row(HTMAlefHandle this, HTMAlefHandle ctx, const char* cells, int32_t is_header);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_table_row(instance, 0, NULL, true);
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `cells` | `const char*` | Yes | The cells |
| `is_header` | `int32_t` | Yes | The is header |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_table_end()
[Section titled “htm_html_visitor_visit_table_end()”](#htm_html_visitor_visit_table_end)
Called after processing a table `</table>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_table_end(HTMAlefHandle this, HTMAlefHandle ctx, const char* output);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_table_end(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `output` | `const char*` | Yes | The output |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_blockquote()
[Section titled “htm_html_visitor_visit_blockquote()”](#htm_html_visitor_visit_blockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_blockquote(HTMAlefHandle this, HTMAlefHandle ctx, const char* content, uintptr_t depth);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_blockquote(instance, 0, "value", 42);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `content` | `const char*` | Yes | The content |
| `depth` | `uintptr_t` | Yes | The depth |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_strong()
[Section titled “htm_html_visitor_visit_strong()”](#htm_html_visitor_visit_strong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_strong(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_strong(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_emphasis()
[Section titled “htm_html_visitor_visit_emphasis()”](#htm_html_visitor_visit_emphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_emphasis(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_emphasis(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_strikethrough()
[Section titled “htm_html_visitor_visit_strikethrough()”](#htm_html_visitor_visit_strikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_strikethrough(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_strikethrough(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_underline()
[Section titled “htm_html_visitor_visit_underline()”](#htm_html_visitor_visit_underline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_underline(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_underline(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_subscript()
[Section titled “htm_html_visitor_visit_subscript()”](#htm_html_visitor_visit_subscript)
Visit subscript elements `<sub>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_subscript(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_subscript(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_superscript()
[Section titled “htm_html_visitor_visit_superscript()”](#htm_html_visitor_visit_superscript)
Visit superscript elements `<sup>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_superscript(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_superscript(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_mark()
[Section titled “htm_html_visitor_visit_mark()”](#htm_html_visitor_visit_mark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_mark(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_mark(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_line_break()
[Section titled “htm_html_visitor_visit_line_break()”](#htm_html_visitor_visit_line_break)
Visit line break elements `<br>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_line_break(HTMAlefHandle this, HTMAlefHandle ctx);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_line_break(instance, 0);
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_horizontal_rule()
[Section titled “htm_html_visitor_visit_horizontal_rule()”](#htm_html_visitor_visit_horizontal_rule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_horizontal_rule(HTMAlefHandle this, HTMAlefHandle ctx);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_horizontal_rule(instance, 0);
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_custom_element()
[Section titled “htm_html_visitor_visit_custom_element()”](#htm_html_visitor_visit_custom_element)
Visit custom elements (web components) or unknown tags.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_custom_element(HTMAlefHandle this, HTMAlefHandle ctx, const char* tag_name, const char* html);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_custom_element(instance, 0, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `tag_name` | `const char*` | Yes | The tag name |
| `html` | `const char*` | Yes | The html |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_definition_list_start()
[Section titled “htm_html_visitor_visit_definition_list_start()”](#htm_html_visitor_visit_definition_list_start)
Visit definition list `<dl>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_definition_list_start(HTMAlefHandle this, HTMAlefHandle ctx);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_definition_list_start(instance, 0);
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_definition_term()
[Section titled “htm_html_visitor_visit_definition_term()”](#htm_html_visitor_visit_definition_term)
Visit definition term `<dt>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_definition_term(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_definition_term(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_definition_description()
[Section titled “htm_html_visitor_visit_definition_description()”](#htm_html_visitor_visit_definition_description)
Visit definition description `<dd>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_definition_description(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_definition_description(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_definition_list_end()
[Section titled “htm_html_visitor_visit_definition_list_end()”](#htm_html_visitor_visit_definition_list_end)
Called after processing a definition list `</dl>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_definition_list_end(HTMAlefHandle this, HTMAlefHandle ctx, const char* output);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_definition_list_end(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `output` | `const char*` | Yes | The output |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_form()
[Section titled “htm_html_visitor_visit_form()”](#htm_html_visitor_visit_form)
Visit form elements `<form>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_form(HTMAlefHandle this, HTMAlefHandle ctx, const char* action, const char* method);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_form(instance, 0, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `action` | `const char*` | No | The action |
| `method` | `const char*` | No | The method |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_input()
[Section titled “htm_html_visitor_visit_input()”](#htm_html_visitor_visit_input)
Visit input elements `<input>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_input(HTMAlefHandle this, HTMAlefHandle ctx, const char* input_type, const char* name, const char* value);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_input(instance, 0, "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `input_type` | `const char*` | Yes | The input type |
| `name` | `const char*` | No | The name |
| `value` | `const char*` | No | The value |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_button()
[Section titled “htm_html_visitor_visit_button()”](#htm_html_visitor_visit_button)
Visit button elements `<button>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_button(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_button(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_audio()
[Section titled “htm_html_visitor_visit_audio()”](#htm_html_visitor_visit_audio)
Visit audio elements `<audio>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_audio(HTMAlefHandle this, HTMAlefHandle ctx, const char* src);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_audio(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `src` | `const char*` | No | The src |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_video()
[Section titled “htm_html_visitor_visit_video()”](#htm_html_visitor_visit_video)
Visit video elements `<video>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_video(HTMAlefHandle this, HTMAlefHandle ctx, const char* src);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_video(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `src` | `const char*` | No | The src |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_iframe()
[Section titled “htm_html_visitor_visit_iframe()”](#htm_html_visitor_visit_iframe)
Visit iframe elements `<iframe>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_iframe(HTMAlefHandle this, HTMAlefHandle ctx, const char* src);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_iframe(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `src` | `const char*` | No | The src |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_details()
[Section titled “htm_html_visitor_visit_details()”](#htm_html_visitor_visit_details)
Visit details elements `<details>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_details(HTMAlefHandle this, HTMAlefHandle ctx, int32_t open);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_details(instance, 0, true);
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `open` | `int32_t` | Yes | The open |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_summary()
[Section titled “htm_html_visitor_visit_summary()”](#htm_html_visitor_visit_summary)
Visit summary elements `<summary>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_summary(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_summary(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_figure_start()
[Section titled “htm_html_visitor_visit_figure_start()”](#htm_html_visitor_visit_figure_start)
Visit figure elements `<figure>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_figure_start(HTMAlefHandle this, HTMAlefHandle ctx);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_figure_start(instance, 0);
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_figcaption()
[Section titled “htm_html_visitor_visit_figcaption()”](#htm_html_visitor_visit_figcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_figcaption(HTMAlefHandle this, HTMAlefHandle ctx, const char* text);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_figcaption(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `text` | `const char*` | Yes | The text |
**Returns:** `HTMAlefHandle`
###### htm_html_visitor_visit_figure_end()
[Section titled “htm_html_visitor_visit_figure_end()”](#htm_html_visitor_visit_figure_end)
Called after processing a figure `</figure>`.
**Signature:**
```c
HTMAlefHandle htm_html_visitor_visit_figure_end(HTMAlefHandle this, HTMAlefHandle ctx, const char* output);
```
**Example:**
```c
HTMAlefHandle result = htm_html_visitor_visit_figure_end(instance, 0, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | --------------- | -------- | ---------------- |
| `ctx` | `HTMAlefHandle` | Yes | The node context |
| `output` | `const char*` | Yes | The output |
**Returns:** `HTMAlefHandle`
***
#### HTMImageDimensions
[Section titled “HTMImageDimensions”](#htmimagedimensions)
**C representation:** `HTMImageDimensions` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMImageDimensions` does not appear anywhere in the generated header.
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `const char***` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ---------- | ------- | ----------------- |
| `width` | `uint32_t` | — | Width in pixels. |
| `height` | `uint32_t` | — | Height in pixels. |
***
#### HTMImageMetadata
[Section titled “HTMImageMetadata”](#htmimagemetadata)
**C representation:** `HTMImageMetadata` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMImageMetadata` does not appear anywhere in the generated header.
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | --------------- | ------- | ------------------------------------------------------- |
| `src` | `const char*` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `const char*` | `NULL` | Alternative text from alt attribute (for accessibility) |
| `title` | `const char*` | `NULL` | Title attribute (often shown as tooltip) |
| `dimensions` | `HTMAlefHandle` | `NULL` | Image dimensions in pixels, if available. |
| `image_type` | `HTMAlefHandle` | — | Image type classification |
| `attributes` | `const char*` | — | Additional HTML attributes |
***
#### HTMLinkMetadata
[Section titled “HTMLinkMetadata”](#htmlinkmetadata)
**C representation:** `HTMLinkMetadata` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMLinkMetadata` does not appear anywhere in the generated header.
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | --------------- | ------- | ------------------------------------------------------------------- |
| `href` | `const char*` | — | The href URL value |
| `text` | `const char*` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `const char*` | `NULL` | Optional title attribute (often shown as tooltip) |
| `link_type` | `HTMAlefHandle` | — | Link type classification |
| `rel` | `const char*` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `const char*` | — | Additional HTML attributes |
***
#### HTMMetadataEntry
[Section titled “HTMMetadataEntry”](#htmmetadataentry)
**C representation:** `HTMMetadataEntry` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMMetadataEntry` does not appear anywhere in the generated header.
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | ------------- | ------- | ------------------------------------------------------------- |
| `key` | `const char*` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `const char*` | — | Metadata value. |
***
#### HTMNodeContext
[Section titled “HTMNodeContext”](#htmnodecontext)
**C representation:** `HTMNodeContext` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMNodeContext` does not appear anywhere in the generated header.
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `void*`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| ----------------- | --------------- | ------- | ------------------------------------------------------- |
| `node_type` | `HTMAlefHandle` | — | Coarse-grained node type classification |
| `tag_name` | `const char*` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `uintptr_t` | — | Depth in the DOM tree (0 = root) |
| `index_in_parent` | `uintptr_t` | — | Index among siblings (0-based) |
| `parent_tag` | `const char*` | `NULL` | Parent element’s tag name (None if root) |
| `is_inline` | `int32_t` | — | Whether this element is treated as inline vs block |
***
#### HTMPreprocessingOptions
[Section titled “HTMPreprocessingOptions”](#htmpreprocessingoptions)
**C representation:** `HTMPreprocessingOptions` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMPreprocessingOptions` does not appear anywhere in the generated header.
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------- | --------------- | -------------- | -------------------------------------------------------------- |
| `enabled` | `int32_t` | `true` | Enable HTML preprocessing globally |
| `preset` | `HTMAlefHandle` | `HTM_STANDARD` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `remove_navigation` | `int32_t` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `remove_forms` | `int32_t` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### HTMProcessingWarning
[Section titled “HTMProcessingWarning”](#htmprocessingwarning)
**C representation:** `HTMProcessingWarning` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMProcessingWarning` does not appear anywhere in the generated header.
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | --------------- | ------- | ------------------------------- |
| `message` | `const char*` | — | Human-readable warning message. |
| `kind` | `HTMAlefHandle` | — | The category of warning. |
***
#### HTMStructuredData
[Section titled “HTMStructuredData”](#htmstructureddata)
**C representation:** `HTMStructuredData` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMStructuredData` does not appear anywhere in the generated header.
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------- | --------------- | ------- | --------------------------------------------------------------- |
| `data_type` | `HTMAlefHandle` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `raw_json` | `const char*` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schema_type` | `const char*` | `NULL` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### HTMTableData
[Section titled “HTMTableData”](#htmtabledata)
**C representation:** `HTMTableData` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMTableData` does not appear anywhere in the generated header.
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | --------------- | ------- | ------------------------------------- |
| `grid` | `HTMAlefHandle` | — | The structured table grid. |
| `markdown` | `const char*` | — | The markdown rendering of this table. |
***
#### HTMTableGrid
[Section titled “HTMTableGrid”](#htmtablegrid)
**C representation:** `HTMTableGrid` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMTableGrid` does not appear anywhere in the generated header.
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `uint32_t` | — | Number of rows. |
| `cols` | `uint32_t` | — | Number of columns. |
| `cells` | `const char*` | `NULL` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### HTMTextAnnotation
[Section titled “HTMTextAnnotation”](#htmtextannotation)
**C representation:** `HTMTextAnnotation` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMTextAnnotation` does not appear anywhere in the generated header.
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | --------------- | ------- | ---------------------------------------------------------- |
| `start` | `uint32_t` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `uint32_t` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `HTMAlefHandle` | — | The type of annotation. |
***
#### HTMVisitorHandle
[Section titled “HTMVisitorHandle”](#htmvisitorhandle)
**C representation:** `HTMVisitorHandle` is a documentation-only name for this type. The C ABI hands you a scalar `HTMAlefHandle` handle – the literal string `HTMVisitorHandle` does not appear anywhere in the generated header.
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### HTMTextDirection
[Section titled “HTMTextDirection”](#htmtextdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------------- | ---------------------------------------------------- |
| `HTM_LEFT_TO_RIGHT` | Left-to-right text flow (default for Latin scripts) |
| `HTM_RIGHT_TO_LEFT` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `HTM_AUTO` | Automatic directionality detection |
***
#### HTMLinkType
[Section titled “HTMLinkType”](#htmlinktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| -------------- | ----------------------------------------------------- |
| `HTM_ANCHOR` | Anchor link within same document (href starts with #) |
| `HTM_INTERNAL` | Internal link within same domain |
| `HTM_EXTERNAL` | External link to different domain |
| `HTM_EMAIL` | Email link (mailto:) |
| `HTM_PHONE` | Phone link (tel:) |
| `HTM_OTHER` | Other protocol or unclassifiable |
***
#### HTMImageType
[Section titled “HTMImageType”](#htmimagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ---------------- | -------------------------------------------------- |
| `HTM_DATA_URI` | Data URI embedded image (base64 or other encoding) |
| `HTM_INLINE_SVG` | Inline SVG element |
| `HTM_EXTERNAL` | External image URL (http/https) |
| `HTM_RELATIVE` | Relative image path |
***
#### HTMStructuredDataType
[Section titled “HTMStructuredDataType”](#htmstructureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| --------------- | ---------------------------------------------------------- |
| `HTM_JSON_LD` | JSON-LD (JSON for Linking Data) script blocks |
| `HTM_MICRODATA` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `HTM_RDFA` | RDF in Attributes (`RDFa`) markup |
***
#### HTMTierStrategy
[Section titled “HTMTierStrategy”](#htmtierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HTM_AUTO` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `HTM_TIER2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `HTM_TIER1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### HTMPreprocessingPreset
[Section titled “HTMPreprocessingPreset”](#htmpreprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ---------------- | ---------------------------------------------------------------------------------- |
| `HTM_MINIMAL` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `HTM_STANDARD` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `HTM_AGGRESSIVE` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HTMHeadingStyle
[Section titled “HTMHeadingStyle”](#htmheadingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ---------------- | -------------------------------------------------- |
| `HTM_UNDERLINED` | Underlined style (=== for h1, — for h2). |
| `HTM_ATX` | ATX style (# for h1, ## for h2, etc.). Default. |
| `HTM_ATX_CLOSED` | ATX closed style (# title #, with closing hashes). |
***
#### HTMListIndentType
[Section titled “HTMListIndentType”](#htmlistindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| ------------ | ----------------------------------------------------------------------------- |
| `HTM_SPACES` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `HTM_TABS` | Use tabs for indentation. |
***
#### HTMWhitespaceMode
[Section titled “HTMWhitespaceMode”](#htmwhitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `HTM_NORMALIZED` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `HTM_STRICT` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### HTMNewlineStyle
[Section titled “HTMNewlineStyle”](#htmnewlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| --------------- | ---------------------------------------------------------------------- |
| `HTM_SPACES` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `HTM_BACKSLASH` | Backslash at end of line. Alternative Markdown syntax. |
***
#### HTMCodeBlockStyle
[Section titled “HTMCodeBlockStyle”](#htmcodeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| --------------- | --------------------------------------------------------------------------------- |
| `HTM_INDENTED` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `HTM_BACKTICKS` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `HTM_TILDES` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HTMHighlightStyle
[Section titled “HTMHighlightStyle”](#htmhighlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------------ | ------------------------------------------------------------ |
| `HTM_DOUBLE_EQUAL` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `HTM_HTML` | Preserve as HTML (==text==). Original HTML tag. |
| `HTM_BOLD` | Render as bold (**text**). Uses strong emphasis. |
| `HTM_NONE` | Strip formatting, render as plain text. No markup. |
***
#### HTMLinkStyle
[Section titled “HTMLinkStyle”](#htmlinkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| --------------- | ---------------------------------------------------------------------- |
| `HTM_INLINE` | Inline links: `text`. Default. |
| `HTM_REFERENCE` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### HTMUrlEscapeStyle
[Section titled “HTMUrlEscapeStyle”](#htmurlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| ------------- | ----------------------------------------------------------------------------- |
| `HTM_ANGLE` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `HTM_PERCENT` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### HTMInlineDataMedia
[Section titled “HTMInlineDataMedia”](#htminlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `HTM_KEEP` | Write the `data:` URL as the destination, payload included. Default. |
| `HTM_ALT_TEXT_ONLY` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `HTM_DROP_ELEMENT` | Write nothing for the element. |
***
#### HTMHiddenContent
[Section titled “HTMHiddenContent”](#htmhiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HTM_DROP` | Drop the text a browser does not show at first. Default. |
| `HTM_REACHABLE` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `HTM_ALL` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### HTMOutputFormat
[Section titled “HTMOutputFormat”](#htmoutputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| -------------- | ----------------------------------------------------- |
| `HTM_MARKDOWN` | Standard Markdown (`CommonMark` compatible). Default. |
| `HTM_DJOT` | Djot lightweight markup language. |
| `HTM_PLAIN` | Plain text output (no markup, visible text only). |
***
#### HTMNodeContent
[Section titled “HTMNodeContent”](#htmnodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HTM_HEADING` | A heading element (h1-h6). — Fields: `level`: `uint8_t`, `text`: `const char*` |
| `HTM_PARAGRAPH` | A paragraph of text. — Fields: `text`: `const char*` |
| `HTM_LIST` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `int32_t` |
| `HTM_LIST_ITEM` | A single list item. — Fields: `text`: `const char*` |
| `HTM_TABLE` | A table with structured cell data. — Fields: `grid`: `HTMAlefHandle` |
| `HTM_IMAGE` | An image element. — Fields: `description`: `const char*`, `src`: `const char*`, `image_index`: `uint32_t` |
| `HTM_CODE` | A code block or inline code. — Fields: `text`: `const char*`, `language`: `const char*` |
| `HTM_QUOTE` | A block quote container. |
| `HTM_DEFINITION_LIST` | A definition list container. |
| `HTM_DEFINITION_ITEM` | A definition list entry with term and description. — Fields: `term`: `const char*`, `definition`: `const char*` |
| `HTM_RAW_BLOCK` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `const char*`, `content`: `const char*` |
| `HTM_METADATA_BLOCK` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `const char*` |
| `HTM_GROUP` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `const char*`, `heading_level`: `uint8_t`, `heading_text`: `const char*` |
***
#### HTMAnnotationKind
[Section titled “HTMAnnotationKind”](#htmannotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `HTM_BOLD` | Bold / strong emphasis. |
| `HTM_ITALIC` | Italic / emphasis. |
| `HTM_UNDERLINE` | Underline. |
| `HTM_STRIKETHROUGH` | Strikethrough / deleted text. |
| `HTM_CODE` | Inline code. |
| `HTM_SUBSCRIPT` | Subscript text. |
| `HTM_SUPERSCRIPT` | Superscript text. |
| `HTM_HIGHLIGHT` | Highlighted / marked text. |
| `HTM_LINK` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `const char*`, `title`: `const char*` |
***
#### HTMWarningKind
[Section titled “HTMWarningKind”](#htmwarningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------------- | ---------------------------------------------------------------------------- |
| `HTM_IMAGE_EXTRACTION_FAILED` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `HTM_ENCODING_FALLBACK` | The input encoding was not recognized; fell back to UTF-8. |
| `HTM_TRUNCATED_INPUT` | The input was truncated due to size limits. |
| `HTM_MALFORMED_HTML` | The HTML was malformed but processing continued with best effort. |
| `HTM_SANITIZATION_APPLIED` | Sanitization was applied to remove potentially unsafe content. |
| `HTM_DEPTH_LIMIT_EXCEEDED` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### HTMNodeType
[Section titled “HTMNodeType”](#htmnodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ---------------------------- | ---------------------------------------------- |
| `HTM_TEXT` | Text node (most frequent - 100+ per document) |
| `HTM_ELEMENT` | Generic element node |
| `HTM_HEADING` | Heading elements (h1-h6) |
| `HTM_PARAGRAPH` | Paragraph element |
| `HTM_DIV` | Generic div container |
| `HTM_BLOCKQUOTE` | Blockquote element |
| `HTM_PRE` | Preformatted text block |
| `HTM_HR` | Horizontal rule |
| `HTM_LIST` | Ordered or unordered list (ul, ol) |
| `HTM_LIST_ITEM` | List item (li) |
| `HTM_DEFINITION_LIST` | Definition list (dl) |
| `HTM_DEFINITION_TERM` | Definition term (dt) |
| `HTM_DEFINITION_DESCRIPTION` | Definition description (dd) |
| `HTM_TABLE` | Table element |
| `HTM_TABLE_ROW` | Table row (tr) |
| `HTM_TABLE_CELL` | Table cell (td, th) |
| `HTM_TABLE_HEADER` | Table header cell (th) |
| `HTM_TABLE_BODY` | Table body (tbody) |
| `HTM_TABLE_HEAD` | Table head (thead) |
| `HTM_TABLE_FOOT` | Table foot (tfoot) |
| `HTM_LINK` | Anchor link (a) |
| `HTM_IMAGE` | Image (img) |
| `HTM_STRONG` | Strong/bold (strong, b) |
| `HTM_EM` | Emphasis/italic (em, i) |
| `HTM_CODE` | Inline code (code) |
| `HTM_STRIKETHROUGH` | Strikethrough (s, del, strike) |
| `HTM_UNDERLINE` | Underline (u, ins) |
| `HTM_SUBSCRIPT` | Subscript (sub) |
| `HTM_SUPERSCRIPT` | Superscript (sup) |
| `HTM_MARK` | Mark/highlight (mark) |
| `HTM_SMALL` | Small text (small) |
| `HTM_BR` | Line break (br) |
| `HTM_SPAN` | Span element |
| `HTM_ARTICLE` | Article element |
| `HTM_SECTION` | Section element |
| `HTM_NAV` | Navigation element |
| `HTM_ASIDE` | Aside element |
| `HTM_HEADER` | Header element |
| `HTM_FOOTER` | Footer element |
| `HTM_MAIN` | Main element |
| `HTM_FIGURE` | Figure element |
| `HTM_FIGCAPTION` | Figure caption |
| `HTM_TIME` | Time element |
| `HTM_DETAILS` | Details element |
| `HTM_SUMMARY` | Summary element |
| `HTM_FORM` | Form element |
| `HTM_INPUT` | Input element |
| `HTM_SELECT` | Select element |
| `HTM_OPTION` | Option element |
| `HTM_BUTTON` | Button element |
| `HTM_TEXTAREA` | Textarea element |
| `HTM_LABEL` | Label element |
| `HTM_FIELDSET` | Fieldset element |
| `HTM_LEGEND` | Legend element |
| `HTM_AUDIO` | Audio element |
| `HTM_VIDEO` | Video element |
| `HTM_PICTURE` | Picture element |
| `HTM_SOURCE` | Source element |
| `HTM_IFRAME` | Iframe element |
| `HTM_SVG` | SVG element |
| `HTM_CANVAS` | Canvas element |
| `HTM_RUBY` | Ruby annotation |
| `HTM_RT` | Ruby text |
| `HTM_RP` | Ruby parenthesis |
| `HTM_ABBR` | Abbreviation |
| `HTM_KBD` | Keyboard input |
| `HTM_SAMP` | Sample output |
| `HTM_VAR` | Variable |
| `HTM_CITE` | Citation |
| `HTM_Q` | Quote |
| `HTM_DEL` | Deleted text |
| `HTM_INS` | Inserted text |
| `HTM_DATA` | Data element |
| `HTM_METER` | Meter element |
| `HTM_PROGRESS` | Progress element |
| `HTM_OUTPUT` | Output element |
| `HTM_TEMPLATE` | Template element |
| `HTM_SLOT` | Slot element |
| `HTM_HTML` | HTML root element |
| `HTM_HEAD` | Head element |
| `HTM_BODY` | Body element |
| `HTM_TITLE` | Title element |
| `HTM_META` | Meta element |
| `HTM_LINK_TAG` | Link element (not anchor) |
| `HTM_STYLE` | Style element |
| `HTM_SCRIPT` | Script element |
| `HTM_BASE` | Base element |
| `HTM_CUSTOM` | Custom element (web components) or unknown tag |
***
#### HTMVisitResult
[Section titled “HTMVisitResult”](#htmvisitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HTM_CONTINUE` | Continue with default conversion behavior |
| `HTM_CUSTOM` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `const char*` |
| `HTM_SKIP` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `HTM_PRESERVE_HTML` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `HTM_ERROR` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `const char*` |
***
### Errors
[Section titled “Errors”](#errors)
#### HTMConversionError
[Section titled “HTMConversionError”](#htmconversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HTM_PARSE_ERROR` | HTML parsing error |
| `HTM_SANITIZATION_ERROR` | HTML sanitization error |
| `HTM_CONFIG_ERROR` | Invalid configuration |
| `HTM_IO_ERROR` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `HTM_PANIC` | Internal error caught during conversion |
| `HTM_INVALID_INPUT` | Invalid input data |
| `HTM_INPUT_TOO_LARGE` | Input exceeds the configured byte limit. |
| `HTM_OTHER` | Generic conversion error |
***
# C# API Reference
## C# API Reference v3.17.2
[Section titled “C# API Reference v3.17.2”](#c-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### Convert()
[Section titled “Convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```csharp
public static ConversionResult Convert(string html, ConversionOptions? options = null)
```
**Example:**
```csharp
var result = HtmlToMarkdownConverter.Convert("value", new ConversionOptions());
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------------- | -------- | ------------------ |
| `Html` | `string` | Yes | The html |
| `Options` | `ConversionOptions?` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Throws `ConversionError`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ---------------------------- | ---------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HeadingStyle` | `HeadingStyle` | `HeadingStyle.Atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `ListIndentType` | `ListIndentType` | `ListIndentType.Spaces` | How to indent nested list items (spaces or tab). |
| `ListIndentWidth` | `ulong` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `Bullets` | `string` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `StrongEmSymbol` | `string` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `EscapeAsterisks` | `bool` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `EscapeUnderscores` | `bool` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `EscapeMisc` | `bool` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `EscapeAscii` | `bool` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `CodeLanguage` | `string` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `Autolinks` | `bool` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `ExpandAbbreviations` | `bool` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `IncludeBlockquoteCitations` | `bool` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `DefaultTitle` | `bool` | `false` | Emit a default title when no `<title>` tag is present. |
| `BrInTables` | `bool` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `CompactTables` | `bool` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `HighlightStyle` | `HighlightStyle` | `HighlightStyle.DoubleEqual` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `ExtractMetadata` | `bool` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `WhitespaceMode` | `WhitespaceMode` | `WhitespaceMode.Normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `StripNewlines` | `bool` | `false` | Strip all newlines from the output, producing a single-line result. |
| `Wrap` | `bool` | `false` | Wrap long lines at `wrap_width` characters. |
| `WrapWidth` | `ulong` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `ConvertAsInline` | `bool` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `SubSymbol` | `string` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `SupSymbol` | `string` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `NewlineStyle` | `NewlineStyle` | `NewlineStyle.Spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `CodeBlockStyle` | `CodeBlockStyle` | `CodeBlockStyle.Backticks` | Style used for fenced code blocks (backticks or tilde). |
| `KeepInlineImagesIn` | `List<string>` | `new List<string>()` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `Preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `Encoding` | `string` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `Debug` | `bool` | `false` | Emit debug information during conversion. |
| `StripTags` | `List<string>` | `new List<string>()` | HTML tag names whose content is stripped from the output entirely. |
| `PreserveTags` | `List<string>` | `new List<string>()` | HTML tag names that are preserved verbatim in the output. |
| `SkipImages` | `bool` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `InlineDataMedia` | `InlineDataMedia` | `InlineDataMedia.Keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `HiddenContent` | `HiddenContent` | `HiddenContent.Drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `UrlEscapeStyle` | `UrlEscapeStyle` | `UrlEscapeStyle.Angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `LinkStyle` | `LinkStyle` | `LinkStyle.Inline` | Link rendering style (inline or reference). |
| `OutputFormat` | `OutputFormat` | `OutputFormat.Markdown` | Target output format (Markdown, plain text, etc.). |
| `IncludeDocumentStructure` | `bool` | `false` | Include structured document tree in result. |
| `ExtractImages` | `bool` | `false` | Extract inline images from data URIs and SVGs. |
| `MaxImageSize` | `ulong` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `MaxInputSize` | `ulong?` | `null` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `null`. Set `Some(bytes)` to choose another limit or `null` to disable it. |
| `CaptureSvg` | `bool` | `false` | Capture SVG elements as images. |
| `InferDimensions` | `bool` | `true` | Infer image dimensions from data. |
| `MaxDepth` | `ulong?` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `ExcludeSelectors` | `List<string>` | `new List<string>()` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `TierStrategy` | `TierStrategy` | `TierStrategy.Auto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `BaseUrl` | `string?` | `null` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `null` — no resolution, output byte-identical to versions before this option existed. |
| `Visitor` | `VisitorHandle?` | `null` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | ------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content` | `string?` | `null` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `Document` | `DocumentStructure?` | `null` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `null` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `Metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `Tables` | `List<TableData>` | `new List<TableData>()` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `Warnings` | `List<ProcessingWarning>` | `new List<ProcessingWarning>()` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| --------------- | ---------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Title` | `string?` | `null` | Document title from `<title>` tag |
| `Description` | `string?` | `null` | Document description from `<meta name="description">` tag |
| `Keywords` | `List<string>` | `new List<string>()` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `Author` | `string?` | `null` | Document author from `<meta name="author">` tag |
| `CanonicalUrl` | `string?` | `null` | Canonical URL from `<link rel="canonical">` tag |
| `BaseHref` | `string?` | `null` | Base URL from `<base href="">` tag for resolving relative URLs |
| `Language` | `string?` | `null` | Document language from `lang` attribute |
| `TextDirection` | `TextDirection?` | `null` | Document text direction from `dir` attribute |
| `OpenGraph` | `Dictionary<string, string>` | `new Dictionary<string, string>()` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `TwitterCard` | `Dictionary<string, string>` | `new Dictionary<string, string>()` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `MetaTags` | `Dictionary<string, string>` | `new Dictionary<string, string>()` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ----------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Id` | `string` | — | Deterministic node identifier. |
| `Content` | `NodeContent` | — | The semantic content of this node. |
| `Parent` | `uint?` | `null` | Index of the parent node (None for root nodes). |
| `Children` | `List<uint>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `Annotations` | `List<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `Attributes` | `Dictionary<string, string>?` | `null` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `null` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| -------------- | -------------------- | ------- | --------------------------------------------------- |
| `Nodes` | `List<DocumentNode>` | — | All nodes in document reading order. |
| `SourceFormat` | `string?` | `null` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ---------- | -------- | ---------------------- | ---------------------------------------------- |
| `Content` | `string` | — | The text content of the cell. |
| `Row` | `uint` | — | 0-indexed row position. |
| `Col` | `uint` | — | 0-indexed column position. |
| `RowSpan` | `uint` | `1` | Number of rows this cell spans (default 1). |
| `ColSpan` | `uint` | `1` | Number of columns this cell spans (default 1). |
| `IsHeader` | `bool` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------ | --------- | ------- | ----------------------------------------- |
| `Level` | `byte` | — | Header level: 1 (h1) through 6 (h6) |
| `Text` | `string` | — | Normalized text content of the header |
| `Id` | `string?` | `null` | HTML id attribute if present |
| `Depth` | `ulong` | — | Document tree depth at the header element |
| `HtmlOffset` | `ulong` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ---------------- | ---------------------- | ---------------------------- | ------------------------------------------------------------- |
| `Document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `Headers` | `List<HeaderMetadata>` | `new List<HeaderMetadata>()` | Extracted header elements with hierarchy |
| `Links` | `List<LinkMetadata>` | `new List<LinkMetadata>()` | Extracted hyperlinks with type classification |
| `Images` | `List<ImageMetadata>` | `new List<ImageMetadata>()` | Extracted images with source and dimensions |
| `StructuredData` | `List<StructuredData>` | `new List<StructuredData>()` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### VisitText()
[Section titled “VisitText()”](#visittext)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```csharp
public VisitResult VisitText(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitText(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitElementStart()
[Section titled “VisitElementStart()”](#visitelementstart)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```csharp
public VisitResult VisitElementStart(NodeContext ctx)
```
**Example:**
```csharp
var result = instance.VisitElementStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitElementEnd()
[Section titled “VisitElementEnd()”](#visitelementend)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```csharp
public VisitResult VisitElementEnd(NodeContext ctx, string output)
```
**Example:**
```csharp
var result = instance.VisitElementEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### VisitLink()
[Section titled “VisitLink()”](#visitlink)
Visit anchor links `<a href="...">`.
**Signature:**
```csharp
public VisitResult VisitLink(NodeContext ctx, string href, string text, string title)
```
**Example:**
```csharp
var result = instance.VisitLink(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Href` | `string` | Yes | The href |
| `Text` | `string` | Yes | The text |
| `Title` | `string?` | No | The title |
**Returns:** `VisitResult`
###### VisitImage()
[Section titled “VisitImage()”](#visitimage)
Visit images `<img src="...">`.
**Signature:**
```csharp
public VisitResult VisitImage(NodeContext ctx, string src, string alt, string title)
```
**Example:**
```csharp
var result = instance.VisitImage(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Src` | `string` | Yes | The src |
| `Alt` | `string` | Yes | The alt |
| `Title` | `string?` | No | The title |
**Returns:** `VisitResult`
###### VisitHeading()
[Section titled “VisitHeading()”](#visitheading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```csharp
public VisitResult VisitHeading(NodeContext ctx, uint level, string text, string id)
```
**Example:**
```csharp
var result = instance.VisitHeading(new NodeContext(), 42, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Level` | `uint` | Yes | The level |
| `Text` | `string` | Yes | The text |
| `Id` | `string?` | No | The id |
**Returns:** `VisitResult`
###### VisitCodeBlock()
[Section titled “VisitCodeBlock()”](#visitcodeblock)
Visit code blocks `<pre><code>`.
**Signature:**
```csharp
public VisitResult VisitCodeBlock(NodeContext ctx, string lang, string code)
```
**Example:**
```csharp
var result = instance.VisitCodeBlock(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Lang` | `string?` | No | The lang |
| `Code` | `string` | Yes | The code |
**Returns:** `VisitResult`
###### VisitCodeInline()
[Section titled “VisitCodeInline()”](#visitcodeinline)
Visit inline code `<code>`.
**Signature:**
```csharp
public VisitResult VisitCodeInline(NodeContext ctx, string code)
```
**Example:**
```csharp
var result = instance.VisitCodeInline(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Code` | `string` | Yes | The code |
**Returns:** `VisitResult`
###### VisitListItem()
[Section titled “VisitListItem()”](#visitlistitem)
Visit list items `<li>`.
**Signature:**
```csharp
public VisitResult VisitListItem(NodeContext ctx, bool ordered, string marker, string text)
```
**Example:**
```csharp
var result = instance.VisitListItem(new NodeContext(), true, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Ordered` | `bool` | Yes | The ordered |
| `Marker` | `string` | Yes | The marker |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitListStart()
[Section titled “VisitListStart()”](#visitliststart)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```csharp
public VisitResult VisitListStart(NodeContext ctx, bool ordered)
```
**Example:**
```csharp
var result = instance.VisitListStart(new NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Ordered` | `bool` | Yes | The ordered |
**Returns:** `VisitResult`
###### VisitListEnd()
[Section titled “VisitListEnd()”](#visitlistend)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```csharp
public VisitResult VisitListEnd(NodeContext ctx, bool ordered, string output)
```
**Example:**
```csharp
var result = instance.VisitListEnd(new NodeContext(), true, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Ordered` | `bool` | Yes | The ordered |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### VisitTableStart()
[Section titled “VisitTableStart()”](#visittablestart)
Called before processing a table `<table>`.
**Signature:**
```csharp
public VisitResult VisitTableStart(NodeContext ctx)
```
**Example:**
```csharp
var result = instance.VisitTableStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitTableRow()
[Section titled “VisitTableRow()”](#visittablerow)
Visit table rows `<tr>`.
**Signature:**
```csharp
public VisitResult VisitTableRow(NodeContext ctx, List<string> cells, bool isHeader)
```
**Example:**
```csharp
var result = instance.VisitTableRow(new NodeContext(), new List<object>(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | -------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Cells` | `List<string>` | Yes | The cells |
| `IsHeader` | `bool` | Yes | The is header |
**Returns:** `VisitResult`
###### VisitTableEnd()
[Section titled “VisitTableEnd()”](#visittableend)
Called after processing a table `</table>`.
**Signature:**
```csharp
public VisitResult VisitTableEnd(NodeContext ctx, string output)
```
**Example:**
```csharp
var result = instance.VisitTableEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### VisitBlockquote()
[Section titled “VisitBlockquote()”](#visitblockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```csharp
public VisitResult VisitBlockquote(NodeContext ctx, string content, ulong depth)
```
**Example:**
```csharp
var result = instance.VisitBlockquote(new NodeContext(), "value", 42);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Content` | `string` | Yes | The content |
| `Depth` | `ulong` | Yes | The depth |
**Returns:** `VisitResult`
###### VisitStrong()
[Section titled “VisitStrong()”](#visitstrong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```csharp
public VisitResult VisitStrong(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitStrong(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitEmphasis()
[Section titled “VisitEmphasis()”](#visitemphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```csharp
public VisitResult VisitEmphasis(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitEmphasis(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitStrikethrough()
[Section titled “VisitStrikethrough()”](#visitstrikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```csharp
public VisitResult VisitStrikethrough(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitStrikethrough(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitUnderline()
[Section titled “VisitUnderline()”](#visitunderline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```csharp
public VisitResult VisitUnderline(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitUnderline(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitSubscript()
[Section titled “VisitSubscript()”](#visitsubscript)
Visit subscript elements `<sub>`.
**Signature:**
```csharp
public VisitResult VisitSubscript(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitSubscript(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitSuperscript()
[Section titled “VisitSuperscript()”](#visitsuperscript)
Visit superscript elements `<sup>`.
**Signature:**
```csharp
public VisitResult VisitSuperscript(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitSuperscript(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitMark()
[Section titled “VisitMark()”](#visitmark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```csharp
public VisitResult VisitMark(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitMark(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitLineBreak()
[Section titled “VisitLineBreak()”](#visitlinebreak)
Visit line break elements `<br>`.
**Signature:**
```csharp
public VisitResult VisitLineBreak(NodeContext ctx)
```
**Example:**
```csharp
var result = instance.VisitLineBreak(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitHorizontalRule()
[Section titled “VisitHorizontalRule()”](#visithorizontalrule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```csharp
public VisitResult VisitHorizontalRule(NodeContext ctx)
```
**Example:**
```csharp
var result = instance.VisitHorizontalRule(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitCustomElement()
[Section titled “VisitCustomElement()”](#visitcustomelement)
Visit custom elements (web components) or unknown tags.
**Signature:**
```csharp
public VisitResult VisitCustomElement(NodeContext ctx, string tagName, string html)
```
**Example:**
```csharp
var result = instance.VisitCustomElement(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `TagName` | `string` | Yes | The tag name |
| `Html` | `string` | Yes | The html |
**Returns:** `VisitResult`
###### VisitDefinitionListStart()
[Section titled “VisitDefinitionListStart()”](#visitdefinitionliststart)
Visit definition list `<dl>`.
**Signature:**
```csharp
public VisitResult VisitDefinitionListStart(NodeContext ctx)
```
**Example:**
```csharp
var result = instance.VisitDefinitionListStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitDefinitionTerm()
[Section titled “VisitDefinitionTerm()”](#visitdefinitionterm)
Visit definition term `<dt>`.
**Signature:**
```csharp
public VisitResult VisitDefinitionTerm(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitDefinitionTerm(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitDefinitionDescription()
[Section titled “VisitDefinitionDescription()”](#visitdefinitiondescription)
Visit definition description `<dd>`.
**Signature:**
```csharp
public VisitResult VisitDefinitionDescription(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitDefinitionDescription(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitDefinitionListEnd()
[Section titled “VisitDefinitionListEnd()”](#visitdefinitionlistend)
Called after processing a definition list `</dl>`.
**Signature:**
```csharp
public VisitResult VisitDefinitionListEnd(NodeContext ctx, string output)
```
**Example:**
```csharp
var result = instance.VisitDefinitionListEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### VisitForm()
[Section titled “VisitForm()”](#visitform)
Visit form elements `<form>`.
**Signature:**
```csharp
public VisitResult VisitForm(NodeContext ctx, string action, string method)
```
**Example:**
```csharp
var result = instance.VisitForm(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Action` | `string?` | No | The action |
| `Method` | `string?` | No | The method |
**Returns:** `VisitResult`
###### VisitInput()
[Section titled “VisitInput()”](#visitinput)
Visit input elements `<input>`.
**Signature:**
```csharp
public VisitResult VisitInput(NodeContext ctx, string inputType, string name, string value)
```
**Example:**
```csharp
var result = instance.VisitInput(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `InputType` | `string` | Yes | The input type |
| `Name` | `string?` | No | The name |
| `Value` | `string?` | No | The value |
**Returns:** `VisitResult`
###### VisitButton()
[Section titled “VisitButton()”](#visitbutton)
Visit button elements `<button>`.
**Signature:**
```csharp
public VisitResult VisitButton(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitButton(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitAudio()
[Section titled “VisitAudio()”](#visitaudio)
Visit audio elements `<audio>`.
**Signature:**
```csharp
public VisitResult VisitAudio(NodeContext ctx, string src)
```
**Example:**
```csharp
var result = instance.VisitAudio(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Src` | `string?` | No | The src |
**Returns:** `VisitResult`
###### VisitVideo()
[Section titled “VisitVideo()”](#visitvideo)
Visit video elements `<video>`.
**Signature:**
```csharp
public VisitResult VisitVideo(NodeContext ctx, string src)
```
**Example:**
```csharp
var result = instance.VisitVideo(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Src` | `string?` | No | The src |
**Returns:** `VisitResult`
###### VisitIframe()
[Section titled “VisitIframe()”](#visitiframe)
Visit iframe elements `<iframe>`.
**Signature:**
```csharp
public VisitResult VisitIframe(NodeContext ctx, string src)
```
**Example:**
```csharp
var result = instance.VisitIframe(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Src` | `string?` | No | The src |
**Returns:** `VisitResult`
###### VisitDetails()
[Section titled “VisitDetails()”](#visitdetails)
Visit details elements `<details>`.
**Signature:**
```csharp
public VisitResult VisitDetails(NodeContext ctx, bool open)
```
**Example:**
```csharp
var result = instance.VisitDetails(new NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Open` | `bool` | Yes | The open |
**Returns:** `VisitResult`
###### VisitSummary()
[Section titled “VisitSummary()”](#visitsummary)
Visit summary elements `<summary>`.
**Signature:**
```csharp
public VisitResult VisitSummary(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitSummary(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitFigureStart()
[Section titled “VisitFigureStart()”](#visitfigurestart)
Visit figure elements `<figure>`.
**Signature:**
```csharp
public VisitResult VisitFigureStart(NodeContext ctx)
```
**Example:**
```csharp
var result = instance.VisitFigureStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitFigcaption()
[Section titled “VisitFigcaption()”](#visitfigcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```csharp
public VisitResult VisitFigcaption(NodeContext ctx, string text)
```
**Example:**
```csharp
var result = instance.VisitFigcaption(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitFigureEnd()
[Section titled “VisitFigureEnd()”](#visitfigureend)
Called after processing a figure `</figure>`.
**Signature:**
```csharp
public VisitResult VisitFigureEnd(NodeContext ctx, string output)
```
**Example:**
```csharp
var result = instance.VisitFigureEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `List<List<string>>` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ------ | ------- | ----------------- |
| `Width` | `uint` | — | Width in pixels. |
| `Height` | `uint` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ---------------------------- | ------- | ------------------------------------------------------- |
| `Src` | `string` | — | Image source (URL, data URI, or SVG content identifier) |
| `Alt` | `string?` | `null` | Alternative text from alt attribute (for accessibility) |
| `Title` | `string?` | `null` | Title attribute (often shown as tooltip) |
| `Dimensions` | `ImageDimensions?` | `null` | Image dimensions in pixels, if available. |
| `ImageType` | `ImageType` | — | Image type classification |
| `Attributes` | `Dictionary<string, string>` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ---------------------------- | ------- | ------------------------------------------------------------------- |
| `Href` | `string` | — | The href URL value |
| `Text` | `string` | — | Link text content (normalized, concatenated if mixed with elements) |
| `Title` | `string?` | `null` | Optional title attribute (often shown as tooltip) |
| `LinkType` | `LinkType` | — | Link type classification |
| `Rel` | `List<string>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `Attributes` | `Dictionary<string, string>` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `Key` | `string` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `Value` | `string` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `Dictionary<string, string>`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| --------------- | ---------- | ------- | ------------------------------------------------------- |
| `NodeType` | `NodeType` | — | Coarse-grained node type classification |
| `TagName` | `string` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `Depth` | `ulong` | — | Depth in the DOM tree (0 = root) |
| `IndexInParent` | `ulong` | — | Index among siblings (0-based) |
| `ParentTag` | `string?` | `null` | Parent element’s tag name (None if root) |
| `IsInline` | `bool` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------ | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `Enabled` | `bool` | `true` | Enable HTML preprocessing globally |
| `Preset` | `PreprocessingPreset` | `PreprocessingPreset.Standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `RemoveNavigation` | `bool` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `RemoveForms` | `bool` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `Message` | `string` | — | Human-readable warning message. |
| `Kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | --------------------------------------------------------------- |
| `DataType` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `RawJson` | `string` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `SchemaType` | `string?` | `null` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `Grid` | `TableGrid` | — | The structured table grid. |
| `Markdown` | `string` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Rows` | `uint` | — | Number of rows. |
| `Cols` | `uint` | — | Number of columns. |
| `Cells` | `List<GridCell>` | `new List<GridCell>()` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `Start` | `uint` | — | Start byte offset (inclusive) into the parent node’s text. |
| `End` | `uint` | — | End byte offset (exclusive) into the parent node’s text. |
| `Kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------- | ---------------------------------------------------- |
| `LeftToRight` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Anchor` | Anchor link within same document (href starts with #) |
| `Internal` | Internal link within same domain |
| `External` | External link to different domain |
| `Email` | Email link (mailto:) |
| `Phone` | Phone link (tel:) |
| `Other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ----------- | -------------------------------------------------- |
| `DataUri` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | Inline SVG element |
| `External` | External image URL (http/https) |
| `Relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JsonLd` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `Rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `Tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | A heading element (h1-h6). — Fields: `Level`: `byte`, `Text`: `string` |
| `Paragraph` | A paragraph of text. — Fields: `Text`: `string` |
| `List` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `Ordered`: `bool` |
| `ListItem` | A single list item. — Fields: `Text`: `string` |
| `Table` | A table with structured cell data. — Fields: `Grid`: `TableGrid` |
| `Image` | An image element. — Fields: `Description`: `string`, `Src`: `string`, `ImageIndex`: `uint` |
| `Code` | A code block or inline code. — Fields: `Text`: `string`, `Language`: `string` |
| `Quote` | A block quote container. |
| `DefinitionList` | A definition list container. |
| `DefinitionItem` | A definition list entry with term and description. — Fields: `Term`: `string`, `Definition`: `string` |
| `RawBlock` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `Format`: `string`, `Content`: `string` |
| `MetadataBlock` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `Entries`: `List<MetadataEntry>` |
| `Group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `Label`: `string`, `HeadingLevel`: `byte`, `HeadingText`: `string` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | Bold / strong emphasis. |
| `Italic` | Italic / emphasis. |
| `Underline` | Underline. |
| `Strikethrough` | Strikethrough / deleted text. |
| `Code` | Inline code. |
| `Subscript` | Subscript text. |
| `Superscript` | Superscript text. |
| `Highlight` | Highlighted / marked text. |
| `Link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `Url`: `string`, `Title`: `string` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | The input was truncated due to size limits. |
| `MalformedHtml` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ----------------------- | ---------------------------------------------- |
| `Text` | Text node (most frequent - 100+ per document) |
| `Element` | Generic element node |
| `Heading` | Heading elements (h1-h6) |
| `Paragraph` | Paragraph element |
| `Div` | Generic div container |
| `Blockquote` | Blockquote element |
| `Pre` | Preformatted text block |
| `Hr` | Horizontal rule |
| `List` | Ordered or unordered list (ul, ol) |
| `ListItem` | List item (li) |
| `DefinitionList` | Definition list (dl) |
| `DefinitionTerm` | Definition term (dt) |
| `DefinitionDescription` | Definition description (dd) |
| `Table` | Table element |
| `TableRow` | Table row (tr) |
| `TableCell` | Table cell (td, th) |
| `TableHeader` | Table header cell (th) |
| `TableBody` | Table body (tbody) |
| `TableHead` | Table head (thead) |
| `TableFoot` | Table foot (tfoot) |
| `Link` | Anchor link (a) |
| `Image` | Image (img) |
| `Strong` | Strong/bold (strong, b) |
| `Em` | Emphasis/italic (em, i) |
| `Code` | Inline code (code) |
| `Strikethrough` | Strikethrough (s, del, strike) |
| `Underline` | Underline (u, ins) |
| `Subscript` | Subscript (sub) |
| `Superscript` | Superscript (sup) |
| `Mark` | Mark/highlight (mark) |
| `Small` | Small text (small) |
| `Br` | Line break (br) |
| `Span` | Span element |
| `Article` | Article element |
| `Section` | Section element |
| `Nav` | Navigation element |
| `Aside` | Aside element |
| `Header` | Header element |
| `Footer` | Footer element |
| `Main` | Main element |
| `Figure` | Figure element |
| `Figcaption` | Figure caption |
| `Time` | Time element |
| `Details` | Details element |
| `Summary` | Summary element |
| `Form` | Form element |
| `Input` | Input element |
| `Select` | Select element |
| `Option` | Option element |
| `Button` | Button element |
| `Textarea` | Textarea element |
| `Label` | Label element |
| `Fieldset` | Fieldset element |
| `Legend` | Legend element |
| `Audio` | Audio element |
| `Video` | Video element |
| `Picture` | Picture element |
| `Source` | Source element |
| `Iframe` | Iframe element |
| `Svg` | SVG element |
| `Canvas` | Canvas element |
| `Ruby` | Ruby annotation |
| `Rt` | Ruby text |
| `Rp` | Ruby parenthesis |
| `Abbr` | Abbreviation |
| `Kbd` | Keyboard input |
| `Samp` | Sample output |
| `Var` | Variable |
| `Cite` | Citation |
| `Q` | Quote |
| `Del` | Deleted text |
| `Ins` | Inserted text |
| `Data` | Data element |
| `Meter` | Meter element |
| `Progress` | Progress element |
| `Output` | Output element |
| `Template` | Template element |
| `Slot` | Slot element |
| `Html` | HTML root element |
| `Head` | Head element |
| `Body` | Body element |
| `Title` | Title element |
| `Meta` | Meta element |
| `LinkTag` | Link element (not anchor) |
| `Style` | Style element |
| `Script` | Script element |
| `Base` | Base element |
| `Custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Continue` | Continue with default conversion behavior |
| `Custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `string` |
| `Skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PreserveHtml` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `Error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `string` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseErrorException` | HTML parsing error |
| `SanitizationErrorException` | HTML sanitization error |
| `ConfigErrorException` | Invalid configuration |
| `IoErrorException` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `PanicException` | Internal error caught during conversion |
| `InvalidInputException` | Invalid input data |
| `InputTooLargeException` | Input exceeds the configured byte limit. |
| `OtherException` | Generic conversion error |
***
# Dart API Reference
## Dart API Reference v3.17.2
[Section titled “Dart API Reference v3.17.2”](#dart-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```dart
Future<ConversionResult> convert(String html, {ConversionOptions? options})
```
**Example:**
```dart
final result = convert("value", ConversionOptions());
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------------- | -------- | ------------------ |
| `html` | `String` | Yes | The html |
| `options` | `ConversionOptions?` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Throws `ConversionError`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ---------------------------- | ---------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `headingStyle` | `HeadingStyle` | `HeadingStyle.atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `listIndentType` | `ListIndentType` | `ListIndentType.spaces` | How to indent nested list items (spaces or tab). |
| `listIndentWidth` | `PlatformInt64` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `String` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strongEmSymbol` | `String` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escapeAsterisks` | `bool` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escapeUnderscores` | `bool` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escapeMisc` | `bool` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escapeAscii` | `bool` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `codeLanguage` | `String` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `bool` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expandAbbreviations` | `bool` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `includeBlockquoteCitations` | `bool` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `defaultTitle` | `bool` | `false` | Emit a default title when no `<title>` tag is present. |
| `brInTables` | `bool` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compactTables` | `bool` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlightStyle` | `HighlightStyle` | `HighlightStyle.doubleEqual` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extractMetadata` | `bool` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespaceMode` | `WhitespaceMode` | `WhitespaceMode.normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `stripNewlines` | `bool` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `bool` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrapWidth` | `PlatformInt64` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convertAsInline` | `bool` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `subSymbol` | `String` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `supSymbol` | `String` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newlineStyle` | `NewlineStyle` | `NewlineStyle.spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `codeBlockStyle` | `CodeBlockStyle` | `CodeBlockStyle.backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keepInlineImagesIn` | `List<String>` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `String` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `bool` | `false` | Emit debug information during conversion. |
| `stripTags` | `List<String>` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserveTags` | `List<String>` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skipImages` | `bool` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inlineDataMedia` | `InlineDataMedia` | `InlineDataMedia.keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hiddenContent` | `HiddenContent` | `HiddenContent.drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `urlEscapeStyle` | `UrlEscapeStyle` | `UrlEscapeStyle.angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `linkStyle` | `LinkStyle` | `LinkStyle.inline` | Link rendering style (inline or reference). |
| `outputFormat` | `OutputFormat` | `OutputFormat.markdown` | Target output format (Markdown, plain text, etc.). |
| `includeDocumentStructure` | `bool` | `false` | Include structured document tree in result. |
| `extractImages` | `bool` | `false` | Extract inline images from data URIs and SVGs. |
| `maxImageSize` | `int` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `maxInputSize` | `int?` | `null` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `null`. Set `Some(bytes)` to choose another limit or `null` to disable it. |
| `captureSvg` | `bool` | `false` | Capture SVG elements as images. |
| `inferDimensions` | `bool` | `true` | Infer image dimensions from data. |
| `maxDepth` | `PlatformInt64?` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `excludeSelectors` | `List<String>` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tierStrategy` | `TierStrategy` | `TierStrategy.auto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `baseUrl` | `String?` | `null` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `null` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle?` | `null` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `String?` | `null` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure?` | `null` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `null` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `List<TableData>` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `List<ProcessingWarning>` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| --------------- | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `String?` | `null` | Document title from `<title>` tag |
| `description` | `String?` | `null` | Document description from `<meta name="description">` tag |
| `keywords` | `List<String>` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `String?` | `null` | Document author from `<meta name="author">` tag |
| `canonicalUrl` | `String?` | `null` | Canonical URL from `<link rel="canonical">` tag |
| `baseHref` | `String?` | `null` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `String?` | `null` | Document language from `lang` attribute |
| `textDirection` | `TextDirection?` | `null` | Document text direction from `dir` attribute |
| `openGraph` | `Map<String, String>` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitterCard` | `Map<String, String>` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `metaTags` | `Map<String, String>` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ---------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `String` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `int?` | `null` | Index of the parent node (None for root nodes). |
| `children` | `List<int>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `List<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `Map<String, String>?` | `null` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `null` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| -------------- | -------------------- | ------- | --------------------------------------------------- |
| `nodes` | `List<DocumentNode>` | — | All nodes in document reading order. |
| `sourceFormat` | `String?` | `null` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ---------- | -------- | ---------------------- | ---------------------------------------------- |
| `content` | `String` | — | The text content of the cell. |
| `row` | `int` | — | 0-indexed row position. |
| `col` | `int` | — | 0-indexed column position. |
| `rowSpan` | `int` | `1` | Number of rows this cell spans (default 1). |
| `colSpan` | `int` | `1` | Number of columns this cell spans (default 1). |
| `isHeader` | `bool` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------ | --------------- | ------- | ----------------------------------------- |
| `level` | `int` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `String` | — | Normalized text content of the header |
| `id` | `String?` | `null` | HTML id attribute if present |
| `depth` | `PlatformInt64` | — | Document tree depth at the header element |
| `htmlOffset` | `PlatformInt64` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ---------------- | ---------------------- | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `List<HeaderMetadata>` | `[]` | Extracted header elements with hierarchy |
| `links` | `List<LinkMetadata>` | `[]` | Extracted hyperlinks with type classification |
| `images` | `List<ImageMetadata>` | `[]` | Extracted images with source and dimensions |
| `structuredData` | `List<StructuredData>` | `[]` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### visitText()
[Section titled “visitText()”](#visittext)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```dart
Future<VisitResult> visitText(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitText(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitElementStart()
[Section titled “visitElementStart()”](#visitelementstart)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```dart
Future<VisitResult> visitElementStart(NodeContext ctx)
```
**Example:**
```dart
final result = instance.visitElementStart(NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitElementEnd()
[Section titled “visitElementEnd()”](#visitelementend)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```dart
Future<VisitResult> visitElementEnd(NodeContext ctx, String output)
```
**Example:**
```dart
final result = instance.visitElementEnd(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitLink()
[Section titled “visitLink()”](#visitlink)
Visit anchor links `<a href="...">`.
**Signature:**
```dart
Future<VisitResult> visitLink(NodeContext ctx, String href, String text, {String? title})
```
**Example:**
```dart
final result = instance.visitLink(NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `href` | `String` | Yes | The href |
| `text` | `String` | Yes | The text |
| `title` | `String?` | No | The title |
**Returns:** `VisitResult`
###### visitImage()
[Section titled “visitImage()”](#visitimage)
Visit images `<img src="...">`.
**Signature:**
```dart
Future<VisitResult> visitImage(NodeContext ctx, String src, String alt, {String? title})
```
**Example:**
```dart
final result = instance.visitImage(NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String` | Yes | The src |
| `alt` | `String` | Yes | The alt |
| `title` | `String?` | No | The title |
**Returns:** `VisitResult`
###### visitHeading()
[Section titled “visitHeading()”](#visitheading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```dart
Future<VisitResult> visitHeading(NodeContext ctx, int level, String text, {String? id})
```
**Example:**
```dart
final result = instance.visitHeading(NodeContext(), 42, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `level` | `int` | Yes | The level |
| `text` | `String` | Yes | The text |
| `id` | `String?` | No | The id |
**Returns:** `VisitResult`
###### visitCodeBlock()
[Section titled “visitCodeBlock()”](#visitcodeblock)
Visit code blocks `<pre><code>`.
**Signature:**
```dart
Future<VisitResult> visitCodeBlock(NodeContext ctx, String code, {String? lang})
```
**Example:**
```dart
final result = instance.visitCodeBlock(NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `lang` | `String?` | No | The lang |
| `code` | `String` | Yes | The code |
**Returns:** `VisitResult`
###### visitCodeInline()
[Section titled “visitCodeInline()”](#visitcodeinline)
Visit inline code `<code>`.
**Signature:**
```dart
Future<VisitResult> visitCodeInline(NodeContext ctx, String code)
```
**Example:**
```dart
final result = instance.visitCodeInline(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `code` | `String` | Yes | The code |
**Returns:** `VisitResult`
###### visitListItem()
[Section titled “visitListItem()”](#visitlistitem)
Visit list items `<li>`.
**Signature:**
```dart
Future<VisitResult> visitListItem(NodeContext ctx, bool ordered, String marker, String text)
```
**Example:**
```dart
final result = instance.visitListItem(NodeContext(), true, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
| `marker` | `String` | Yes | The marker |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitListStart()
[Section titled “visitListStart()”](#visitliststart)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```dart
Future<VisitResult> visitListStart(NodeContext ctx, bool ordered)
```
**Example:**
```dart
final result = instance.visitListStart(NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
**Returns:** `VisitResult`
###### visitListEnd()
[Section titled “visitListEnd()”](#visitlistend)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```dart
Future<VisitResult> visitListEnd(NodeContext ctx, bool ordered, String output)
```
**Example:**
```dart
final result = instance.visitListEnd(NodeContext(), true, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitTableStart()
[Section titled “visitTableStart()”](#visittablestart)
Called before processing a table `<table>`.
**Signature:**
```dart
Future<VisitResult> visitTableStart(NodeContext ctx)
```
**Example:**
```dart
final result = instance.visitTableStart(NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitTableRow()
[Section titled “visitTableRow()”](#visittablerow)
Visit table rows `<tr>`.
**Signature:**
```dart
Future<VisitResult> visitTableRow(NodeContext ctx, List<String> cells, bool isHeader)
```
**Example:**
```dart
final result = instance.visitTableRow(NodeContext(), [], true);
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | -------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `cells` | `List<String>` | Yes | The cells |
| `isHeader` | `bool` | Yes | The is header |
**Returns:** `VisitResult`
###### visitTableEnd()
[Section titled “visitTableEnd()”](#visittableend)
Called after processing a table `</table>`.
**Signature:**
```dart
Future<VisitResult> visitTableEnd(NodeContext ctx, String output)
```
**Example:**
```dart
final result = instance.visitTableEnd(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitBlockquote()
[Section titled “visitBlockquote()”](#visitblockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```dart
Future<VisitResult> visitBlockquote(NodeContext ctx, String content, PlatformInt64 depth)
```
**Example:**
```dart
final result = instance.visitBlockquote(NodeContext(), "value", 42);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `content` | `String` | Yes | The content |
| `depth` | `PlatformInt64` | Yes | The depth |
**Returns:** `VisitResult`
###### visitStrong()
[Section titled “visitStrong()”](#visitstrong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```dart
Future<VisitResult> visitStrong(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitStrong(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitEmphasis()
[Section titled “visitEmphasis()”](#visitemphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```dart
Future<VisitResult> visitEmphasis(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitEmphasis(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitStrikethrough()
[Section titled “visitStrikethrough()”](#visitstrikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```dart
Future<VisitResult> visitStrikethrough(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitStrikethrough(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitUnderline()
[Section titled “visitUnderline()”](#visitunderline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```dart
Future<VisitResult> visitUnderline(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitUnderline(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitSubscript()
[Section titled “visitSubscript()”](#visitsubscript)
Visit subscript elements `<sub>`.
**Signature:**
```dart
Future<VisitResult> visitSubscript(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitSubscript(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitSuperscript()
[Section titled “visitSuperscript()”](#visitsuperscript)
Visit superscript elements `<sup>`.
**Signature:**
```dart
Future<VisitResult> visitSuperscript(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitSuperscript(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitMark()
[Section titled “visitMark()”](#visitmark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```dart
Future<VisitResult> visitMark(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitMark(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitLineBreak()
[Section titled “visitLineBreak()”](#visitlinebreak)
Visit line break elements `<br>`.
**Signature:**
```dart
Future<VisitResult> visitLineBreak(NodeContext ctx)
```
**Example:**
```dart
final result = instance.visitLineBreak(NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitHorizontalRule()
[Section titled “visitHorizontalRule()”](#visithorizontalrule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```dart
Future<VisitResult> visitHorizontalRule(NodeContext ctx)
```
**Example:**
```dart
final result = instance.visitHorizontalRule(NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitCustomElement()
[Section titled “visitCustomElement()”](#visitcustomelement)
Visit custom elements (web components) or unknown tags.
**Signature:**
```dart
Future<VisitResult> visitCustomElement(NodeContext ctx, String tagName, String html)
```
**Example:**
```dart
final result = instance.visitCustomElement(NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `tagName` | `String` | Yes | The tag name |
| `html` | `String` | Yes | The html |
**Returns:** `VisitResult`
###### visitDefinitionListStart()
[Section titled “visitDefinitionListStart()”](#visitdefinitionliststart)
Visit definition list `<dl>`.
**Signature:**
```dart
Future<VisitResult> visitDefinitionListStart(NodeContext ctx)
```
**Example:**
```dart
final result = instance.visitDefinitionListStart(NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitDefinitionTerm()
[Section titled “visitDefinitionTerm()”](#visitdefinitionterm)
Visit definition term `<dt>`.
**Signature:**
```dart
Future<VisitResult> visitDefinitionTerm(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitDefinitionTerm(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionDescription()
[Section titled “visitDefinitionDescription()”](#visitdefinitiondescription)
Visit definition description `<dd>`.
**Signature:**
```dart
Future<VisitResult> visitDefinitionDescription(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitDefinitionDescription(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionListEnd()
[Section titled “visitDefinitionListEnd()”](#visitdefinitionlistend)
Called after processing a definition list `</dl>`.
**Signature:**
```dart
Future<VisitResult> visitDefinitionListEnd(NodeContext ctx, String output)
```
**Example:**
```dart
final result = instance.visitDefinitionListEnd(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitForm()
[Section titled “visitForm()”](#visitform)
Visit form elements `<form>`.
**Signature:**
```dart
Future<VisitResult> visitForm(NodeContext ctx, {String? action, String? method})
```
**Example:**
```dart
final result = instance.visitForm(NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `action` | `String?` | No | The action |
| `method` | `String?` | No | The method |
**Returns:** `VisitResult`
###### visitInput()
[Section titled “visitInput()”](#visitinput)
Visit input elements `<input>`.
**Signature:**
```dart
Future<VisitResult> visitInput(NodeContext ctx, String inputType, {String? name, String? value})
```
**Example:**
```dart
final result = instance.visitInput(NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `inputType` | `String` | Yes | The input type |
| `name` | `String?` | No | The name |
| `value` | `String?` | No | The value |
**Returns:** `VisitResult`
###### visitButton()
[Section titled “visitButton()”](#visitbutton)
Visit button elements `<button>`.
**Signature:**
```dart
Future<VisitResult> visitButton(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitButton(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitAudio()
[Section titled “visitAudio()”](#visitaudio)
Visit audio elements `<audio>`.
**Signature:**
```dart
Future<VisitResult> visitAudio(NodeContext ctx, {String? src})
```
**Example:**
```dart
final result = instance.visitAudio(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String?` | No | The src |
**Returns:** `VisitResult`
###### visitVideo()
[Section titled “visitVideo()”](#visitvideo)
Visit video elements `<video>`.
**Signature:**
```dart
Future<VisitResult> visitVideo(NodeContext ctx, {String? src})
```
**Example:**
```dart
final result = instance.visitVideo(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String?` | No | The src |
**Returns:** `VisitResult`
###### visitIframe()
[Section titled “visitIframe()”](#visitiframe)
Visit iframe elements `<iframe>`.
**Signature:**
```dart
Future<VisitResult> visitIframe(NodeContext ctx, {String? src})
```
**Example:**
```dart
final result = instance.visitIframe(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String?` | No | The src |
**Returns:** `VisitResult`
###### visitDetails()
[Section titled “visitDetails()”](#visitdetails)
Visit details elements `<details>`.
**Signature:**
```dart
Future<VisitResult> visitDetails(NodeContext ctx, bool open)
```
**Example:**
```dart
final result = instance.visitDetails(NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `open` | `bool` | Yes | The open |
**Returns:** `VisitResult`
###### visitSummary()
[Section titled “visitSummary()”](#visitsummary)
Visit summary elements `<summary>`.
**Signature:**
```dart
Future<VisitResult> visitSummary(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitSummary(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureStart()
[Section titled “visitFigureStart()”](#visitfigurestart)
Visit figure elements `<figure>`.
**Signature:**
```dart
Future<VisitResult> visitFigureStart(NodeContext ctx)
```
**Example:**
```dart
final result = instance.visitFigureStart(NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitFigcaption()
[Section titled “visitFigcaption()”](#visitfigcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```dart
Future<VisitResult> visitFigcaption(NodeContext ctx, String text)
```
**Example:**
```dart
final result = instance.visitFigcaption(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureEnd()
[Section titled “visitFigureEnd()”](#visitfigureend)
Called after processing a figure `</figure>`.
**Signature:**
```dart
Future<VisitResult> visitFigureEnd(NodeContext ctx, String output)
```
**Example:**
```dart
final result = instance.visitFigureEnd(NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `List<List<String>>` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ----- | ------- | ----------------- |
| `width` | `int` | — | Width in pixels. |
| `height` | `int` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | --------------------- | ------- | ------------------------------------------------------- |
| `src` | `String` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `String?` | `null` | Alternative text from alt attribute (for accessibility) |
| `title` | `String?` | `null` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions?` | `null` | Image dimensions in pixels, if available. |
| `imageType` | `ImageType` | — | Image type classification |
| `attributes` | `Map<String, String>` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | --------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `String` | — | The href URL value |
| `text` | `String` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `String?` | `null` | Optional title attribute (often shown as tooltip) |
| `linkType` | `LinkType` | — | Link type classification |
| `rel` | `List<String>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `Map<String, String>` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `String` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `String` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `Map<String, String>`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| --------------- | --------------- | ------- | ------------------------------------------------------- |
| `nodeType` | `NodeType` | — | Coarse-grained node type classification |
| `tagName` | `String` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `PlatformInt64` | — | Depth in the DOM tree (0 = root) |
| `indexInParent` | `PlatformInt64` | — | Index among siblings (0-based) |
| `parentTag` | `String?` | `null` | Parent element’s tag name (None if root) |
| `isInline` | `bool` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------ | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `enabled` | `bool` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset.standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `removeNavigation` | `bool` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `removeForms` | `bool` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `String` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | --------------------------------------------------------------- |
| `dataType` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `rawJson` | `String` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schemaType` | `String?` | `null` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `String` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `int` | — | Number of rows. |
| `cols` | `int` | — | Number of columns. |
| `cells` | `List<GridCell>` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `int` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `int` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------- | ---------------------------------------------------- |
| `LeftToRight` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Anchor` | Anchor link within same document (href starts with #) |
| `Internal` | Internal link within same domain |
| `External` | External link to different domain |
| `Email` | Email link (mailto:) |
| `Phone` | Phone link (tel:) |
| `Other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ----------- | -------------------------------------------------- |
| `DataUri` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | Inline SVG element |
| `External` | External image URL (http/https) |
| `Relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JsonLd` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `Rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `Tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | A heading element (h1-h6). — Fields: `level`: `int`, `text`: `String` |
| `Paragraph` | A paragraph of text. — Fields: `text`: `String` |
| `List` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `bool` |
| `ListItem` | A single list item. — Fields: `text`: `String` |
| `Table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `Image` | An image element. — Fields: `description`: `String`, `src`: `String`, `imageIndex`: `int` |
| `Code` | A code block or inline code. — Fields: `text`: `String`, `language`: `String` |
| `Quote` | A block quote container. |
| `DefinitionList` | A definition list container. |
| `DefinitionItem` | A definition list entry with term and description. — Fields: `term`: `String`, `definition`: `String` |
| `RawBlock` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `String`, `content`: `String` |
| `MetadataBlock` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `List<MetadataEntry>` |
| `Group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `String`, `headingLevel`: `int`, `headingText`: `String` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | Bold / strong emphasis. |
| `Italic` | Italic / emphasis. |
| `Underline` | Underline. |
| `Strikethrough` | Strikethrough / deleted text. |
| `Code` | Inline code. |
| `Subscript` | Subscript text. |
| `Superscript` | Superscript text. |
| `Highlight` | Highlighted / marked text. |
| `Link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `String`, `title`: `String` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | The input was truncated due to size limits. |
| `MalformedHtml` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ----------------------- | ---------------------------------------------- |
| `Text` | Text node (most frequent - 100+ per document) |
| `Element` | Generic element node |
| `Heading` | Heading elements (h1-h6) |
| `Paragraph` | Paragraph element |
| `Div` | Generic div container |
| `Blockquote` | Blockquote element |
| `Pre` | Preformatted text block |
| `Hr` | Horizontal rule |
| `List` | Ordered or unordered list (ul, ol) |
| `ListItem` | List item (li) |
| `DefinitionList` | Definition list (dl) |
| `DefinitionTerm` | Definition term (dt) |
| `DefinitionDescription` | Definition description (dd) |
| `Table` | Table element |
| `TableRow` | Table row (tr) |
| `TableCell` | Table cell (td, th) |
| `TableHeader` | Table header cell (th) |
| `TableBody` | Table body (tbody) |
| `TableHead` | Table head (thead) |
| `TableFoot` | Table foot (tfoot) |
| `Link` | Anchor link (a) |
| `Image` | Image (img) |
| `Strong` | Strong/bold (strong, b) |
| `Em` | Emphasis/italic (em, i) |
| `Code` | Inline code (code) |
| `Strikethrough` | Strikethrough (s, del, strike) |
| `Underline` | Underline (u, ins) |
| `Subscript` | Subscript (sub) |
| `Superscript` | Superscript (sup) |
| `Mark` | Mark/highlight (mark) |
| `Small` | Small text (small) |
| `Br` | Line break (br) |
| `Span` | Span element |
| `Article` | Article element |
| `Section` | Section element |
| `Nav` | Navigation element |
| `Aside` | Aside element |
| `Header` | Header element |
| `Footer` | Footer element |
| `Main` | Main element |
| `Figure` | Figure element |
| `Figcaption` | Figure caption |
| `Time` | Time element |
| `Details` | Details element |
| `Summary` | Summary element |
| `Form` | Form element |
| `Input` | Input element |
| `Select` | Select element |
| `Option` | Option element |
| `Button` | Button element |
| `Textarea` | Textarea element |
| `Label` | Label element |
| `Fieldset` | Fieldset element |
| `Legend` | Legend element |
| `Audio` | Audio element |
| `Video` | Video element |
| `Picture` | Picture element |
| `Source` | Source element |
| `Iframe` | Iframe element |
| `Svg` | SVG element |
| `Canvas` | Canvas element |
| `Ruby` | Ruby annotation |
| `Rt` | Ruby text |
| `Rp` | Ruby parenthesis |
| `Abbr` | Abbreviation |
| `Kbd` | Keyboard input |
| `Samp` | Sample output |
| `Var` | Variable |
| `Cite` | Citation |
| `Q` | Quote |
| `Del` | Deleted text |
| `Ins` | Inserted text |
| `Data` | Data element |
| `Meter` | Meter element |
| `Progress` | Progress element |
| `Output` | Output element |
| `Template` | Template element |
| `Slot` | Slot element |
| `Html` | HTML root element |
| `Head` | Head element |
| `Body` | Body element |
| `Title` | Title element |
| `Meta` | Meta element |
| `LinkTag` | Link element (not anchor) |
| `Style` | Style element |
| `Script` | Script element |
| `Base` | Base element |
| `Custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Continue` | Continue with default conversion behavior |
| `Custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `String` |
| `Skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PreserveHtml` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `Error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `String` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseError` | HTML parsing error |
| `SanitizationError` | HTML sanitization error |
| `ConfigError` | Invalid configuration |
| `IoError` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `Panic` | Internal error caught during conversion |
| `InvalidInput` | Invalid input data |
| `InputTooLarge` | Input exceeds the configured byte limit. |
| `Other` | Generic conversion error |
***
# Elixir API Reference
## Elixir API Reference v3.17.2
[Section titled “Elixir API Reference v3.17.2”](#elixir-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```elixir
@spec convert(html, options) :: {:ok, term()} | {:error, term()}
def convert(html, options)
```
**Example:**
```elixir
{:ok, result} = convert("value", %{})
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------------------- | -------- | ------------------ |
| `html` | `String.t()` | Yes | The html |
| `options` | `ConversionOptions \| nil` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Returns `{:error, reason}`
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ------------------------------ | ---------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading_style` | `HeadingStyle` | `:atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `list_indent_type` | `ListIndentType` | `:spaces` | How to indent nested list items (spaces or tab). |
| `list_indent_width` | `integer()` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `String.t()` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strong_em_symbol` | `String.t()` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escape_asterisks` | `boolean()` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escape_underscores` | `boolean()` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escape_misc` | `boolean()` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escape_ascii` | `boolean()` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `code_language` | `String.t()` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `boolean()` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expand_abbreviations` | `boolean()` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `include_blockquote_citations` | `boolean()` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `default_title` | `boolean()` | `false` | Emit a default title when no `<title>` tag is present. |
| `br_in_tables` | `boolean()` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compact_tables` | `boolean()` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlight_style` | `HighlightStyle` | `:double_equal` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extract_metadata` | `boolean()` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespace_mode` | `WhitespaceMode` | `:normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `strip_newlines` | `boolean()` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `boolean()` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrap_width` | `integer()` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convert_as_inline` | `boolean()` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `sub_symbol` | `String.t()` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `sup_symbol` | `String.t()` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newline_style` | `NewlineStyle` | `:spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `code_block_style` | `CodeBlockStyle` | `:backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keep_inline_images_in` | `list(String.t())` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `String.t()` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `boolean()` | `false` | Emit debug information during conversion. |
| `strip_tags` | `list(String.t())` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserve_tags` | `list(String.t())` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skip_images` | `boolean()` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inline_data_media` | `InlineDataMedia` | `:keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hidden_content` | `HiddenContent` | `:drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `url_escape_style` | `UrlEscapeStyle` | `:angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `link_style` | `LinkStyle` | `:inline` | Link rendering style (inline or reference). |
| `output_format` | `OutputFormat` | `:markdown` | Target output format (Markdown, plain text, etc.). |
| `include_document_structure` | `boolean()` | `false` | Include structured document tree in result. |
| `extract_images` | `boolean()` | `false` | Extract inline images from data URIs and SVGs. |
| `max_image_size` | `integer()` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `max_input_size` | `integer() \| nil` | `nil` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `nil`. Set `Some(bytes)` to choose another limit or `nil` to disable it. |
| `capture_svg` | `boolean()` | `false` | Capture SVG elements as images. |
| `infer_dimensions` | `boolean()` | `true` | Infer image dimensions from data. |
| `max_depth` | `integer() \| nil` | `nil` | Maximum DOM traversal depth. `nil` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `exclude_selectors` | `list(String.t())` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tier_strategy` | `TierStrategy` | `:auto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `base_url` | `String.t() \| nil` | `nil` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `nil` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle \| nil` | `nil` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `String.t() \| nil` | `nil` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure \| nil` | `nil` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `nil` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `list(TableData)` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `list(ProcessingWarning)` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| ---------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `String.t() \| nil` | `nil` | Document title from `<title>` tag |
| `description` | `String.t() \| nil` | `nil` | Document description from `<meta name="description">` tag |
| `keywords` | `list(String.t())` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `String.t() \| nil` | `nil` | Document author from `<meta name="author">` tag |
| `canonical_url` | `String.t() \| nil` | `nil` | Canonical URL from `<link rel="canonical">` tag |
| `base_href` | `String.t() \| nil` | `nil` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `String.t() \| nil` | `nil` | Document language from `lang` attribute |
| `text_direction` | `TextDirection \| nil` | `nil` | Document text direction from `dir` attribute |
| `open_graph` | `map()` | `%{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitter_card` | `map()` | `%{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `meta_tags` | `map()` | `%{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ---------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `String.t()` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `integer() \| nil` | `nil` | Index of the parent node (None for root nodes). |
| `children` | `list(integer())` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `list(TextAnnotation)` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `map() \| nil` | `nil` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `nil` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| --------------- | -------------------- | ------- | --------------------------------------------------- |
| `nodes` | `list(DocumentNode)` | — | All nodes in document reading order. |
| `source_format` | `String.t() \| nil` | `nil` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ----------- | ------------ | ---------------------- | ---------------------------------------------- |
| `content` | `String.t()` | — | The text content of the cell. |
| `row` | `integer()` | — | 0-indexed row position. |
| `col` | `integer()` | — | 0-indexed column position. |
| `row_span` | `integer()` | `1` | Number of rows this cell spans (default 1). |
| `col_span` | `integer()` | `1` | Number of columns this cell spans (default 1). |
| `is_header` | `boolean()` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------- | ------------------- | ------- | ----------------------------------------- |
| `level` | `integer()` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `String.t()` | — | Normalized text content of the header |
| `id` | `String.t() \| nil` | `nil` | HTML id attribute if present |
| `depth` | `integer()` | — | Document tree depth at the header element |
| `html_offset` | `integer()` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ----------------- | ---------------------- | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `list(HeaderMetadata)` | `[]` | Extracted header elements with hierarchy |
| `links` | `list(LinkMetadata)` | `[]` | Extracted hyperlinks with type classification |
| `images` | `list(ImageMetadata)` | `[]` | Extracted images with source and dimensions |
| `structured_data` | `list(StructuredData)` | `[]` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Functions
[Section titled “Functions”](#functions-1)
###### visit_text()
[Section titled “visit_text()”](#visit_text)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```elixir
def visit_text(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_text(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_element_start()
[Section titled “visit_element_start()”](#visit_element_start)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```elixir
def visit_element_start(obj, ctx)
```
**Example:**
```elixir
{:ok, result} = instance.visit_element_start(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_element_end()
[Section titled “visit_element_end()”](#visit_element_end)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```elixir
def visit_element_end(obj, ctx, output)
```
**Example:**
```elixir
{:ok, result} = instance.visit_element_end(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String.t()` | Yes | The output |
**Returns:** `VisitResult`
###### visit_link()
[Section titled “visit_link()”](#visit_link)
Visit anchor links `<a href="...">`.
**Signature:**
```elixir
def visit_link(obj, ctx, href, text, title)
```
**Example:**
```elixir
{:ok, result} = instance.visit_link(%{}, "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `href` | `String.t()` | Yes | The href |
| `text` | `String.t()` | Yes | The text |
| `title` | `String.t() \| nil` | No | The title |
**Returns:** `VisitResult`
###### visit_image()
[Section titled “visit_image()”](#visit_image)
Visit images `<img src="...">`.
**Signature:**
```elixir
def visit_image(obj, ctx, src, alt, title)
```
**Example:**
```elixir
{:ok, result} = instance.visit_image(%{}, "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String.t()` | Yes | The src |
| `alt` | `String.t()` | Yes | The alt |
| `title` | `String.t() \| nil` | No | The title |
**Returns:** `VisitResult`
###### visit_heading()
[Section titled “visit_heading()”](#visit_heading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```elixir
def visit_heading(obj, ctx, level, text, id)
```
**Example:**
```elixir
{:ok, result} = instance.visit_heading(%{}, 42, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `level` | `integer()` | Yes | The level |
| `text` | `String.t()` | Yes | The text |
| `id` | `String.t() \| nil` | No | The id |
**Returns:** `VisitResult`
###### visit_code_block()
[Section titled “visit_code_block()”](#visit_code_block)
Visit code blocks `<pre><code>`.
**Signature:**
```elixir
def visit_code_block(obj, ctx, lang, code)
```
**Example:**
```elixir
{:ok, result} = instance.visit_code_block(%{}, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `lang` | `String.t() \| nil` | No | The lang |
| `code` | `String.t()` | Yes | The code |
**Returns:** `VisitResult`
###### visit_code_inline()
[Section titled “visit_code_inline()”](#visit_code_inline)
Visit inline code `<code>`.
**Signature:**
```elixir
def visit_code_inline(obj, ctx, code)
```
**Example:**
```elixir
{:ok, result} = instance.visit_code_inline(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `code` | `String.t()` | Yes | The code |
**Returns:** `VisitResult`
###### visit_list_item()
[Section titled “visit_list_item()”](#visit_list_item)
Visit list items `<li>`.
**Signature:**
```elixir
def visit_list_item(obj, ctx, ordered, marker, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_list_item(%{}, true, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean()` | Yes | The ordered |
| `marker` | `String.t()` | Yes | The marker |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_list_start()
[Section titled “visit_list_start()”](#visit_list_start)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```elixir
def visit_list_start(obj, ctx, ordered)
```
**Example:**
```elixir
{:ok, result} = instance.visit_list_start(%{}, true)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean()` | Yes | The ordered |
**Returns:** `VisitResult`
###### visit_list_end()
[Section titled “visit_list_end()”](#visit_list_end)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```elixir
def visit_list_end(obj, ctx, ordered, output)
```
**Example:**
```elixir
{:ok, result} = instance.visit_list_end(%{}, true, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean()` | Yes | The ordered |
| `output` | `String.t()` | Yes | The output |
**Returns:** `VisitResult`
###### visit_table_start()
[Section titled “visit_table_start()”](#visit_table_start)
Called before processing a table `<table>`.
**Signature:**
```elixir
def visit_table_start(obj, ctx)
```
**Example:**
```elixir
{:ok, result} = instance.visit_table_start(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_table_row()
[Section titled “visit_table_row()”](#visit_table_row)
Visit table rows `<tr>`.
**Signature:**
```elixir
def visit_table_row(obj, ctx, cells, is_header)
```
**Example:**
```elixir
{:ok, result} = instance.visit_table_row(%{}, [], true)
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `cells` | `list(String.t())` | Yes | The cells |
| `is_header` | `boolean()` | Yes | The is header |
**Returns:** `VisitResult`
###### visit_table_end()
[Section titled “visit_table_end()”](#visit_table_end)
Called after processing a table `</table>`.
**Signature:**
```elixir
def visit_table_end(obj, ctx, output)
```
**Example:**
```elixir
{:ok, result} = instance.visit_table_end(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String.t()` | Yes | The output |
**Returns:** `VisitResult`
###### visit_blockquote()
[Section titled “visit_blockquote()”](#visit_blockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```elixir
def visit_blockquote(obj, ctx, content, depth)
```
**Example:**
```elixir
{:ok, result} = instance.visit_blockquote(%{}, "value", 42)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `content` | `String.t()` | Yes | The content |
| `depth` | `integer()` | Yes | The depth |
**Returns:** `VisitResult`
###### visit_strong()
[Section titled “visit_strong()”](#visit_strong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```elixir
def visit_strong(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_strong(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_emphasis()
[Section titled “visit_emphasis()”](#visit_emphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```elixir
def visit_emphasis(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_emphasis(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_strikethrough()
[Section titled “visit_strikethrough()”](#visit_strikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```elixir
def visit_strikethrough(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_strikethrough(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_underline()
[Section titled “visit_underline()”](#visit_underline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```elixir
def visit_underline(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_underline(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_subscript()
[Section titled “visit_subscript()”](#visit_subscript)
Visit subscript elements `<sub>`.
**Signature:**
```elixir
def visit_subscript(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_subscript(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_superscript()
[Section titled “visit_superscript()”](#visit_superscript)
Visit superscript elements `<sup>`.
**Signature:**
```elixir
def visit_superscript(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_superscript(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_mark()
[Section titled “visit_mark()”](#visit_mark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```elixir
def visit_mark(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_mark(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_line_break()
[Section titled “visit_line_break()”](#visit_line_break)
Visit line break elements `<br>`.
**Signature:**
```elixir
def visit_line_break(obj, ctx)
```
**Example:**
```elixir
{:ok, result} = instance.visit_line_break(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_horizontal_rule()
[Section titled “visit_horizontal_rule()”](#visit_horizontal_rule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```elixir
def visit_horizontal_rule(obj, ctx)
```
**Example:**
```elixir
{:ok, result} = instance.visit_horizontal_rule(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_custom_element()
[Section titled “visit_custom_element()”](#visit_custom_element)
Visit custom elements (web components) or unknown tags.
**Signature:**
```elixir
def visit_custom_element(obj, ctx, tag_name, html)
```
**Example:**
```elixir
{:ok, result} = instance.visit_custom_element(%{}, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `tag_name` | `String.t()` | Yes | The tag name |
| `html` | `String.t()` | Yes | The html |
**Returns:** `VisitResult`
###### visit_definition_list_start()
[Section titled “visit_definition_list_start()”](#visit_definition_list_start)
Visit definition list `<dl>`.
**Signature:**
```elixir
def visit_definition_list_start(obj, ctx)
```
**Example:**
```elixir
{:ok, result} = instance.visit_definition_list_start(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_definition_term()
[Section titled “visit_definition_term()”](#visit_definition_term)
Visit definition term `<dt>`.
**Signature:**
```elixir
def visit_definition_term(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_definition_term(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_description()
[Section titled “visit_definition_description()”](#visit_definition_description)
Visit definition description `<dd>`.
**Signature:**
```elixir
def visit_definition_description(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_definition_description(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_list_end()
[Section titled “visit_definition_list_end()”](#visit_definition_list_end)
Called after processing a definition list `</dl>`.
**Signature:**
```elixir
def visit_definition_list_end(obj, ctx, output)
```
**Example:**
```elixir
{:ok, result} = instance.visit_definition_list_end(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String.t()` | Yes | The output |
**Returns:** `VisitResult`
###### visit_form()
[Section titled “visit_form()”](#visit_form)
Visit form elements `<form>`.
**Signature:**
```elixir
def visit_form(obj, ctx, action, method)
```
**Example:**
```elixir
{:ok, result} = instance.visit_form(%{}, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `action` | `String.t() \| nil` | No | The action |
| `method` | `String.t() \| nil` | No | The method |
**Returns:** `VisitResult`
###### visit_input()
[Section titled “visit_input()”](#visit_input)
Visit input elements `<input>`.
**Signature:**
```elixir
def visit_input(obj, ctx, input_type, name, value)
```
**Example:**
```elixir
{:ok, result} = instance.visit_input(%{}, "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------------ | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `input_type` | `String.t()` | Yes | The input type |
| `name` | `String.t() \| nil` | No | The name |
| `value` | `String.t() \| nil` | No | The value |
**Returns:** `VisitResult`
###### visit_button()
[Section titled “visit_button()”](#visit_button)
Visit button elements `<button>`.
**Signature:**
```elixir
def visit_button(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_button(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_audio()
[Section titled “visit_audio()”](#visit_audio)
Visit audio elements `<audio>`.
**Signature:**
```elixir
def visit_audio(obj, ctx, src)
```
**Example:**
```elixir
{:ok, result} = instance.visit_audio(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String.t() \| nil` | No | The src |
**Returns:** `VisitResult`
###### visit_video()
[Section titled “visit_video()”](#visit_video)
Visit video elements `<video>`.
**Signature:**
```elixir
def visit_video(obj, ctx, src)
```
**Example:**
```elixir
{:ok, result} = instance.visit_video(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String.t() \| nil` | No | The src |
**Returns:** `VisitResult`
###### visit_iframe()
[Section titled “visit_iframe()”](#visit_iframe)
Visit iframe elements `<iframe>`.
**Signature:**
```elixir
def visit_iframe(obj, ctx, src)
```
**Example:**
```elixir
{:ok, result} = instance.visit_iframe(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String.t() \| nil` | No | The src |
**Returns:** `VisitResult`
###### visit_details()
[Section titled “visit_details()”](#visit_details)
Visit details elements `<details>`.
**Signature:**
```elixir
def visit_details(obj, ctx, open)
```
**Example:**
```elixir
{:ok, result} = instance.visit_details(%{}, true)
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `open` | `boolean()` | Yes | The open |
**Returns:** `VisitResult`
###### visit_summary()
[Section titled “visit_summary()”](#visit_summary)
Visit summary elements `<summary>`.
**Signature:**
```elixir
def visit_summary(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_summary(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_start()
[Section titled “visit_figure_start()”](#visit_figure_start)
Visit figure elements `<figure>`.
**Signature:**
```elixir
def visit_figure_start(obj, ctx)
```
**Example:**
```elixir
{:ok, result} = instance.visit_figure_start(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_figcaption()
[Section titled “visit_figcaption()”](#visit_figcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```elixir
def visit_figcaption(obj, ctx, text)
```
**Example:**
```elixir
{:ok, result} = instance.visit_figcaption(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String.t()` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_end()
[Section titled “visit_figure_end()”](#visit_figure_end)
Called after processing a figure `</figure>`.
**Signature:**
```elixir
def visit_figure_end(obj, ctx, output)
```
**Example:**
```elixir
{:ok, result} = instance.visit_figure_end(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String.t()` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `list(list(String.t()))` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ----------- | ------- | ----------------- |
| `width` | `integer()` | — | Width in pixels. |
| `height` | `integer()` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ------------------------ | ------- | ------------------------------------------------------- |
| `src` | `String.t()` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `String.t() \| nil` | `nil` | Alternative text from alt attribute (for accessibility) |
| `title` | `String.t() \| nil` | `nil` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions \| nil` | `nil` | Image dimensions in pixels, if available. |
| `image_type` | `ImageType` | — | Image type classification |
| `attributes` | `map()` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `String.t()` | — | The href URL value |
| `text` | `String.t()` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `String.t() \| nil` | `nil` | Optional title attribute (often shown as tooltip) |
| `link_type` | `LinkType` | — | Link type classification |
| `rel` | `list(String.t())` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `map()` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | ------------ | ------- | ------------------------------------------------------------- |
| `key` | `String.t()` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `String.t()` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `map()`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| ----------------- | ------------------- | ------- | ------------------------------------------------------- |
| `node_type` | `NodeType` | — | Coarse-grained node type classification |
| `tag_name` | `String.t()` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `integer()` | — | Depth in the DOM tree (0 = root) |
| `index_in_parent` | `integer()` | — | Index among siblings (0-based) |
| `parent_tag` | `String.t() \| nil` | `nil` | Parent element’s tag name (None if root) |
| `is_inline` | `boolean()` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------- | --------------------- | ----------- | -------------------------------------------------------------- |
| `enabled` | `boolean()` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `:standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `remove_navigation` | `boolean()` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `remove_forms` | `boolean()` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `String.t()` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------- | -------------------- | ------- | --------------------------------------------------------------- |
| `data_type` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `raw_json` | `String.t()` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schema_type` | `String.t() \| nil` | `nil` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ------------ | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `String.t()` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `integer()` | — | Number of rows. |
| `cols` | `integer()` | — | Number of columns. |
| `cells` | `list(GridCell)` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `integer()` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `integer()` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| --------------- | ---------------------------------------------------- |
| `left_to_right` | Left-to-right text flow (default for Latin scripts) |
| `right_to_left` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `anchor` | Anchor link within same document (href starts with #) |
| `internal` | Internal link within same domain |
| `external` | External link to different domain |
| `email` | Email link (mailto:) |
| `phone` | Phone link (tel:) |
| `other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `data_uri` | Data URI embedded image (base64 or other encoding) |
| `inline_svg` | Inline SVG element |
| `external` | External image URL (http/https) |
| `relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `json_ld` | JSON-LD (JSON for Linking Data) script blocks |
| `microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `underlined` | Underlined style (=== for h1, — for h2). |
| `atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `atx_closed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| -------------- | ------------------------------------------------------------ |
| `double_equal` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `html` | Preserve as HTML (==text==). Original HTML tag. |
| `bold` | Render as bold (**text**). Uses strong emphasis. |
| `none` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `inline` | Inline links: `text`. Default. |
| `reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `keep` | Write the `data:` URL as the destination, payload included. Default. |
| `alt_text_only` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `drop_element` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `drop` | Drop the text a browser does not show at first. Default. |
| `reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `all` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `djot` | Djot lightweight markup language. |
| `plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading` | A heading element (h1-h6). — Fields: `level`: `integer()`, `text`: `String.t()` |
| `paragraph` | A paragraph of text. — Fields: `text`: `String.t()` |
| `list` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `boolean()` |
| `list_item` | A single list item. — Fields: `text`: `String.t()` |
| `table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `image` | An image element. — Fields: `description`: `String.t()`, `src`: `String.t()`, `image_index`: `integer()` |
| `code` | A code block or inline code. — Fields: `text`: `String.t()`, `language`: `String.t()` |
| `quote` | A block quote container. |
| `definition_list` | A definition list container. |
| `definition_item` | A definition list entry with term and description. — Fields: `term`: `String.t()`, `definition`: `String.t()` |
| `raw_block` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `String.t()`, `content`: `String.t()` |
| `metadata_block` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `list(MetadataEntry)` |
| `group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `String.t()`, `heading_level`: `integer()`, `heading_text`: `String.t()` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| `bold` | Bold / strong emphasis. |
| `italic` | Italic / emphasis. |
| `underline` | Underline. |
| `strikethrough` | Strikethrough / deleted text. |
| `code` | Inline code. |
| `subscript` | Subscript text. |
| `superscript` | Superscript text. |
| `highlight` | Highlighted / marked text. |
| `link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `String.t()`, `title`: `String.t()` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ------------------------- | ---------------------------------------------------------------------------- |
| `image_extraction_failed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `encoding_fallback` | The input encoding was not recognized; fell back to UTF-8. |
| `truncated_input` | The input was truncated due to size limits. |
| `malformed_html` | The HTML was malformed but processing continued with best effort. |
| `sanitization_applied` | Sanitization was applied to remove potentially unsafe content. |
| `depth_limit_exceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ------------------------ | ---------------------------------------------- |
| `text` | Text node (most frequent - 100+ per document) |
| `element` | Generic element node |
| `heading` | Heading elements (h1-h6) |
| `paragraph` | Paragraph element |
| `div` | Generic div container |
| `blockquote` | Blockquote element |
| `pre` | Preformatted text block |
| `hr` | Horizontal rule |
| `list` | Ordered or unordered list (ul, ol) |
| `list_item` | List item (li) |
| `definition_list` | Definition list (dl) |
| `definition_term` | Definition term (dt) |
| `definition_description` | Definition description (dd) |
| `table` | Table element |
| `table_row` | Table row (tr) |
| `table_cell` | Table cell (td, th) |
| `table_header` | Table header cell (th) |
| `table_body` | Table body (tbody) |
| `table_head` | Table head (thead) |
| `table_foot` | Table foot (tfoot) |
| `link` | Anchor link (a) |
| `image` | Image (img) |
| `strong` | Strong/bold (strong, b) |
| `em` | Emphasis/italic (em, i) |
| `code` | Inline code (code) |
| `strikethrough` | Strikethrough (s, del, strike) |
| `underline` | Underline (u, ins) |
| `subscript` | Subscript (sub) |
| `superscript` | Superscript (sup) |
| `mark` | Mark/highlight (mark) |
| `small` | Small text (small) |
| `br` | Line break (br) |
| `span` | Span element |
| `article` | Article element |
| `section` | Section element |
| `nav` | Navigation element |
| `aside` | Aside element |
| `header` | Header element |
| `footer` | Footer element |
| `main` | Main element |
| `figure` | Figure element |
| `figcaption` | Figure caption |
| `time` | Time element |
| `details` | Details element |
| `summary` | Summary element |
| `form` | Form element |
| `input` | Input element |
| `select` | Select element |
| `option` | Option element |
| `button` | Button element |
| `textarea` | Textarea element |
| `label` | Label element |
| `fieldset` | Fieldset element |
| `legend` | Legend element |
| `audio` | Audio element |
| `video` | Video element |
| `picture` | Picture element |
| `source` | Source element |
| `iframe` | Iframe element |
| `svg` | SVG element |
| `canvas` | Canvas element |
| `ruby` | Ruby annotation |
| `rt` | Ruby text |
| `rp` | Ruby parenthesis |
| `abbr` | Abbreviation |
| `kbd` | Keyboard input |
| `samp` | Sample output |
| `var` | Variable |
| `cite` | Citation |
| `q` | Quote |
| `del` | Deleted text |
| `ins` | Inserted text |
| `data` | Data element |
| `meter` | Meter element |
| `progress` | Progress element |
| `output` | Output element |
| `template` | Template element |
| `slot` | Slot element |
| `html` | HTML root element |
| `head` | Head element |
| `body` | Body element |
| `title` | Title element |
| `meta` | Meta element |
| `link_tag` | Link element (not anchor) |
| `style` | Style element |
| `script` | Script element |
| `base` | Base element |
| `custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `continue` | Continue with default conversion behavior |
| `custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `String.t()` |
| `skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `preserve_html` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `String.t()` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parse_error` | HTML parsing error |
| `sanitization_error` | HTML sanitization error |
| `config_error` | Invalid configuration |
| `io_error` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `panic` | Internal error caught during conversion |
| `invalid_input` | Invalid input data |
| `input_too_large` | Input exceeds the configured byte limit. |
| `other` | Generic conversion error |
***
# Go API Reference
## Go API Reference v3.17.2
[Section titled “Go API Reference v3.17.2”](#go-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### Convert()
[Section titled “Convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```go
func Convert(html string, options ConversionOptions) (*ConversionResult, error)
```
**Example:**
```go
result, err := Convert("value", ConversionOptions{})
if err != nil {
return err
}
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------------- | -------- | ------------------ |
| `HTML` | `string` | Yes | The html |
| `Options` | `*ConversionOptions` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Returns `error`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ---------------------------- | ---------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HeadingStyle` | `HeadingStyle` | `HeadingStyleAtx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `ListIndentType` | `ListIndentType` | `ListIndentTypeSpaces` | How to indent nested list items (spaces or tab). |
| `ListIndentWidth` | `uint` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `Bullets` | `string` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `StrongEmSymbol` | `string` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `EscapeAsterisks` | `bool` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `EscapeUnderscores` | `bool` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `EscapeMisc` | `bool` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `EscapeASCII` | `bool` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `CodeLanguage` | `string` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `Autolinks` | `bool` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `ExpandAbbreviations` | `bool` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `IncludeBlockquoteCitations` | `bool` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `DefaultTitle` | `bool` | `false` | Emit a default title when no `<title>` tag is present. |
| `BrInTables` | `bool` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `CompactTables` | `bool` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `HighlightStyle` | `HighlightStyle` | `HighlightStyleDoubleEqual` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `ExtractMetadata` | `bool` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `WhitespaceMode` | `WhitespaceMode` | `WhitespaceModeNormalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `StripNewlines` | `bool` | `false` | Strip all newlines from the output, producing a single-line result. |
| `Wrap` | `bool` | `false` | Wrap long lines at `wrap_width` characters. |
| `WrapWidth` | `uint` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `ConvertAsInline` | `bool` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `SubSymbol` | `string` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `SupSymbol` | `string` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `NewlineStyle` | `NewlineStyle` | `NewlineStyleSpaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `CodeBlockStyle` | `CodeBlockStyle` | `CodeBlockStyleBackticks` | Style used for fenced code blocks (backticks or tilde). |
| `KeepInlineImagesIn` | `\[\]string` | `nil` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `Preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `Encoding` | `string` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `Debug` | `bool` | `false` | Emit debug information during conversion. |
| `StripTags` | `\[\]string` | `nil` | HTML tag names whose content is stripped from the output entirely. |
| `PreserveTags` | `\[\]string` | `nil` | HTML tag names that are preserved verbatim in the output. |
| `SkipImages` | `bool` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `InlineDataMedia` | `InlineDataMedia` | `InlineDataMediaKeep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `HiddenContent` | `HiddenContent` | `HiddenContentDrop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `URLEscapeStyle` | `URLEscapeStyle` | `URLEscapeStyleAngle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `LinkStyle` | `LinkStyle` | `LinkStyleInline` | Link rendering style (inline or reference). |
| `OutputFormat` | `OutputFormat` | `OutputFormatMarkdown` | Target output format (Markdown, plain text, etc.). |
| `IncludeDocumentStructure` | `bool` | `false` | Include structured document tree in result. |
| `ExtractImages` | `bool` | `false` | Extract inline images from data URIs and SVGs. |
| `MaxImageSize` | `uint64` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `MaxInputSize` | `*uint64` | `nil` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `nil`. Set `Some(bytes)` to choose another limit or `nil` to disable it. |
| `CaptureSvg` | `bool` | `false` | Capture SVG elements as images. |
| `InferDimensions` | `bool` | `true` | Infer image dimensions from data. |
| `MaxDepth` | `*uint` | `nil` | Maximum DOM traversal depth. `nil` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `ExcludeSelectors` | `\[\]string` | `nil` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `TierStrategy` | `TierStrategy` | `TierStrategyAuto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `BaseURL` | `*string` | `nil` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `nil` — no resolution, output byte-identical to versions before this option existed. |
| `Visitor` | `*VisitorHandle` | `nil` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content` | `*string` | `nil` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `Document` | `*DocumentStructure` | `nil` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `nil` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `Metadata` | `HTMLMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `Tables` | `\[\]TableData` | `nil` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `Warnings` | `\[\]ProcessingWarning` | `nil` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| --------------- | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Title` | `*string` | `nil` | Document title from `<title>` tag |
| `Description` | `*string` | `nil` | Document description from `<meta name="description">` tag |
| `Keywords` | `\[\]string` | `nil` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `Author` | `*string` | `nil` | Document author from `<meta name="author">` tag |
| `CanonicalURL` | `*string` | `nil` | Canonical URL from `<link rel="canonical">` tag |
| `BaseHref` | `*string` | `nil` | Base URL from `<base href="">` tag for resolving relative URLs |
| `Language` | `*string` | `nil` | Document language from `lang` attribute |
| `TextDirection` | `*TextDirection` | `nil` | Document text direction from `dir` attribute |
| `OpenGraph` | `map\[string\]string` | `nil` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `TwitterCard` | `map\[string\]string` | `nil` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `MetaTags` | `map\[string\]string` | `nil` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ---------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ID` | `string` | — | Deterministic node identifier. |
| `Content` | `NodeContent` | — | The semantic content of this node. |
| `Parent` | `*uint32` | `nil` | Index of the parent node (None for root nodes). |
| `Children` | `\[\]uint32` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `Annotations` | `\[\]TextAnnotation` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `Attributes` | `*map\[string\]string` | `nil` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `nil` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| -------------- | ------------------ | ------- | --------------------------------------------------- |
| `Nodes` | `\[\]DocumentNode` | — | All nodes in document reading order. |
| `SourceFormat` | `*string` | `nil` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ---------- | -------- | ---------------------- | ---------------------------------------------- |
| `Content` | `string` | — | The text content of the cell. |
| `Row` | `uint32` | — | 0-indexed row position. |
| `Col` | `uint32` | — | 0-indexed column position. |
| `RowSpan` | `uint32` | `1` | Number of rows this cell spans (default 1). |
| `ColSpan` | `uint32` | `1` | Number of columns this cell spans (default 1). |
| `IsHeader` | `bool` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------ | --------- | ------- | ----------------------------------------- |
| `Level` | `uint8` | — | Header level: 1 (h1) through 6 (h6) |
| `Text` | `string` | — | Normalized text content of the header |
| `ID` | `*string` | `nil` | HTML id attribute if present |
| `Depth` | `uint` | — | Document tree depth at the header element |
| `HTMLOffset` | `uint` | — | Byte offset in original HTML document |
##### Methods
[Section titled “Methods”](#methods)
###### IsValid()
[Section titled “IsValid()”](#isvalid)
Validate that the header level is within valid range (1-6).
**Returns:**
`true` if level is 1-6, `false` otherwise.
**Signature:**
```go
func (o *HeaderMetadata) IsValid() bool
```
**Example:**
```go
result := instance.IsValid()
```
**Returns:** `bool`
***
#### HTMLMetadata
[Section titled “HTMLMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ---------------- | -------------------- | ------- | ------------------------------------------------------------- |
| `Document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `Headers` | `\[\]HeaderMetadata` | `nil` | Extracted header elements with hierarchy |
| `Links` | `\[\]LinkMetadata` | `nil` | Extracted hyperlinks with type classification |
| `Images` | `\[\]ImageMetadata` | `nil` | Extracted images with source and dimensions |
| `StructuredData` | `\[\]StructuredData` | `nil` | Extracted structured data blocks |
***
#### HTMLVisitor
[Section titled “HTMLVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods-1)
###### VisitText()
[Section titled “VisitText()”](#visittext)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```go
func (o *HTMLVisitor) VisitText(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitText(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitElementStart()
[Section titled “VisitElementStart()”](#visitelementstart)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```go
func (o *HTMLVisitor) VisitElementStart(ctx NodeContext) *VisitResult
```
**Example:**
```go
result := instance.VisitElementStart(NodeContext{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitElementEnd()
[Section titled “VisitElementEnd()”](#visitelementend)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```go
func (o *HTMLVisitor) VisitElementEnd(ctx NodeContext, output string) *VisitResult
```
**Example:**
```go
result := instance.VisitElementEnd(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### VisitLink()
[Section titled “VisitLink()”](#visitlink)
Visit anchor links `<a href="...">`.
**Signature:**
```go
func (o *HTMLVisitor) VisitLink(ctx NodeContext, href string, text string, title string) *VisitResult
```
**Example:**
```go
result := instance.VisitLink(NodeContext{}, "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Href` | `string` | Yes | The href |
| `Text` | `string` | Yes | The text |
| `Title` | `*string` | No | The title |
**Returns:** `VisitResult`
###### VisitImage()
[Section titled “VisitImage()”](#visitimage)
Visit images `<img src="...">`.
**Signature:**
```go
func (o *HTMLVisitor) VisitImage(ctx NodeContext, src string, alt string, title string) *VisitResult
```
**Example:**
```go
result := instance.VisitImage(NodeContext{}, "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Src` | `string` | Yes | The src |
| `Alt` | `string` | Yes | The alt |
| `Title` | `*string` | No | The title |
**Returns:** `VisitResult`
###### VisitHeading()
[Section titled “VisitHeading()”](#visitheading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitHeading(ctx NodeContext, level uint32, text string, id string) *VisitResult
```
**Example:**
```go
result := instance.VisitHeading(NodeContext{}, 42, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Level` | `uint32` | Yes | The level |
| `Text` | `string` | Yes | The text |
| `ID` | `*string` | No | The id |
**Returns:** `VisitResult`
###### VisitCodeBlock()
[Section titled “VisitCodeBlock()”](#visitcodeblock)
Visit code blocks `<pre><code>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitCodeBlock(ctx NodeContext, lang string, code string) *VisitResult
```
**Example:**
```go
result := instance.VisitCodeBlock(NodeContext{}, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Lang` | `*string` | No | The lang |
| `Code` | `string` | Yes | The code |
**Returns:** `VisitResult`
###### VisitCodeInline()
[Section titled “VisitCodeInline()”](#visitcodeinline)
Visit inline code `<code>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitCodeInline(ctx NodeContext, code string) *VisitResult
```
**Example:**
```go
result := instance.VisitCodeInline(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Code` | `string` | Yes | The code |
**Returns:** `VisitResult`
###### VisitListItem()
[Section titled “VisitListItem()”](#visitlistitem)
Visit list items `<li>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitListItem(ctx NodeContext, ordered bool, marker string, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitListItem(NodeContext{}, true, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Ordered` | `bool` | Yes | The ordered |
| `Marker` | `string` | Yes | The marker |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitListStart()
[Section titled “VisitListStart()”](#visitliststart)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitListStart(ctx NodeContext, ordered bool) *VisitResult
```
**Example:**
```go
result := instance.VisitListStart(NodeContext{}, true)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Ordered` | `bool` | Yes | The ordered |
**Returns:** `VisitResult`
###### VisitListEnd()
[Section titled “VisitListEnd()”](#visitlistend)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitListEnd(ctx NodeContext, ordered bool, output string) *VisitResult
```
**Example:**
```go
result := instance.VisitListEnd(NodeContext{}, true, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Ordered` | `bool` | Yes | The ordered |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### VisitTableStart()
[Section titled “VisitTableStart()”](#visittablestart)
Called before processing a table `<table>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitTableStart(ctx NodeContext) *VisitResult
```
**Example:**
```go
result := instance.VisitTableStart(NodeContext{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitTableRow()
[Section titled “VisitTableRow()”](#visittablerow)
Visit table rows `<tr>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitTableRow(ctx NodeContext, cells []string, isHeader bool) *VisitResult
```
**Example:**
```go
result := instance.VisitTableRow(NodeContext{}, nil, true)
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Cells` | `\[\]string` | Yes | The cells |
| `IsHeader` | `bool` | Yes | The is header |
**Returns:** `VisitResult`
###### VisitTableEnd()
[Section titled “VisitTableEnd()”](#visittableend)
Called after processing a table `</table>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitTableEnd(ctx NodeContext, output string) *VisitResult
```
**Example:**
```go
result := instance.VisitTableEnd(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### VisitBlockquote()
[Section titled “VisitBlockquote()”](#visitblockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitBlockquote(ctx NodeContext, content string, depth uint) *VisitResult
```
**Example:**
```go
result := instance.VisitBlockquote(NodeContext{}, "value", 42)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Content` | `string` | Yes | The content |
| `Depth` | `uint` | Yes | The depth |
**Returns:** `VisitResult`
###### VisitStrong()
[Section titled “VisitStrong()”](#visitstrong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitStrong(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitStrong(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitEmphasis()
[Section titled “VisitEmphasis()”](#visitemphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitEmphasis(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitEmphasis(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitStrikethrough()
[Section titled “VisitStrikethrough()”](#visitstrikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitStrikethrough(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitStrikethrough(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitUnderline()
[Section titled “VisitUnderline()”](#visitunderline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitUnderline(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitUnderline(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitSubscript()
[Section titled “VisitSubscript()”](#visitsubscript)
Visit subscript elements `<sub>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitSubscript(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitSubscript(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitSuperscript()
[Section titled “VisitSuperscript()”](#visitsuperscript)
Visit superscript elements `<sup>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitSuperscript(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitSuperscript(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitMark()
[Section titled “VisitMark()”](#visitmark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitMark(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitMark(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitLineBreak()
[Section titled “VisitLineBreak()”](#visitlinebreak)
Visit line break elements `<br>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitLineBreak(ctx NodeContext) *VisitResult
```
**Example:**
```go
result := instance.VisitLineBreak(NodeContext{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitHorizontalRule()
[Section titled “VisitHorizontalRule()”](#visithorizontalrule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitHorizontalRule(ctx NodeContext) *VisitResult
```
**Example:**
```go
result := instance.VisitHorizontalRule(NodeContext{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitCustomElement()
[Section titled “VisitCustomElement()”](#visitcustomelement)
Visit custom elements (web components) or unknown tags.
**Signature:**
```go
func (o *HTMLVisitor) VisitCustomElement(ctx NodeContext, tagName string, html string) *VisitResult
```
**Example:**
```go
result := instance.VisitCustomElement(NodeContext{}, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `TagName` | `string` | Yes | The tag name |
| `HTML` | `string` | Yes | The html |
**Returns:** `VisitResult`
###### VisitDefinitionListStart()
[Section titled “VisitDefinitionListStart()”](#visitdefinitionliststart)
Visit definition list `<dl>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitDefinitionListStart(ctx NodeContext) *VisitResult
```
**Example:**
```go
result := instance.VisitDefinitionListStart(NodeContext{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitDefinitionTerm()
[Section titled “VisitDefinitionTerm()”](#visitdefinitionterm)
Visit definition term `<dt>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitDefinitionTerm(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitDefinitionTerm(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitDefinitionDescription()
[Section titled “VisitDefinitionDescription()”](#visitdefinitiondescription)
Visit definition description `<dd>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitDefinitionDescription(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitDefinitionDescription(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitDefinitionListEnd()
[Section titled “VisitDefinitionListEnd()”](#visitdefinitionlistend)
Called after processing a definition list `</dl>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitDefinitionListEnd(ctx NodeContext, output string) *VisitResult
```
**Example:**
```go
result := instance.VisitDefinitionListEnd(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### VisitForm()
[Section titled “VisitForm()”](#visitform)
Visit form elements `<form>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitForm(ctx NodeContext, action string, method string) *VisitResult
```
**Example:**
```go
result := instance.VisitForm(NodeContext{}, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Action` | `*string` | No | The action |
| `Method` | `*string` | No | The method |
**Returns:** `VisitResult`
###### VisitInput()
[Section titled “VisitInput()”](#visitinput)
Visit input elements `<input>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitInput(ctx NodeContext, inputType string, name string, value string) *VisitResult
```
**Example:**
```go
result := instance.VisitInput(NodeContext{}, "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `InputType` | `string` | Yes | The input type |
| `Name` | `*string` | No | The name |
| `Value` | `*string` | No | The value |
**Returns:** `VisitResult`
###### VisitButton()
[Section titled “VisitButton()”](#visitbutton)
Visit button elements `<button>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitButton(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitButton(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitAudio()
[Section titled “VisitAudio()”](#visitaudio)
Visit audio elements `<audio>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitAudio(ctx NodeContext, src string) *VisitResult
```
**Example:**
```go
result := instance.VisitAudio(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Src` | `*string` | No | The src |
**Returns:** `VisitResult`
###### VisitVideo()
[Section titled “VisitVideo()”](#visitvideo)
Visit video elements `<video>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitVideo(ctx NodeContext, src string) *VisitResult
```
**Example:**
```go
result := instance.VisitVideo(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Src` | `*string` | No | The src |
**Returns:** `VisitResult`
###### VisitIframe()
[Section titled “VisitIframe()”](#visitiframe)
Visit iframe elements `<iframe>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitIframe(ctx NodeContext, src string) *VisitResult
```
**Example:**
```go
result := instance.VisitIframe(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Src` | `*string` | No | The src |
**Returns:** `VisitResult`
###### VisitDetails()
[Section titled “VisitDetails()”](#visitdetails)
Visit details elements `<details>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitDetails(ctx NodeContext, open bool) *VisitResult
```
**Example:**
```go
result := instance.VisitDetails(NodeContext{}, true)
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Open` | `bool` | Yes | The open |
**Returns:** `VisitResult`
###### VisitSummary()
[Section titled “VisitSummary()”](#visitsummary)
Visit summary elements `<summary>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitSummary(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitSummary(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitFigureStart()
[Section titled “VisitFigureStart()”](#visitfigurestart)
Visit figure elements `<figure>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitFigureStart(ctx NodeContext) *VisitResult
```
**Example:**
```go
result := instance.VisitFigureStart(NodeContext{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### VisitFigcaption()
[Section titled “VisitFigcaption()”](#visitfigcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitFigcaption(ctx NodeContext, text string) *VisitResult
```
**Example:**
```go
result := instance.VisitFigcaption(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### VisitFigureEnd()
[Section titled “VisitFigureEnd()”](#visitfigureend)
Called after processing a figure `</figure>`.
**Signature:**
```go
func (o *HTMLVisitor) VisitFigureEnd(ctx NodeContext, output string) *VisitResult
```
**Example:**
```go
result := instance.VisitFigureEnd(NodeContext{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `Ctx` | `NodeContext` | Yes | The node context |
| `Output` | `string` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `[][]string` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | -------- | ------- | ----------------- |
| `Width` | `uint32` | — | Width in pixels. |
| `Height` | `uint32` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | --------------------- | ------- | ------------------------------------------------------- |
| `Src` | `string` | — | Image source (URL, data URI, or SVG content identifier) |
| `Alt` | `*string` | `nil` | Alternative text from alt attribute (for accessibility) |
| `Title` | `*string` | `nil` | Title attribute (often shown as tooltip) |
| `Dimensions` | `*ImageDimensions` | `nil` | Image dimensions in pixels, if available. |
| `ImageType` | `ImageType` | — | Image type classification |
| `Attributes` | `map\[string\]string` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | --------------------- | ------- | ------------------------------------------------------------------- |
| `Href` | `string` | — | The href URL value |
| `Text` | `string` | — | Link text content (normalized, concatenated if mixed with elements) |
| `Title` | `*string` | `nil` | Optional title attribute (often shown as tooltip) |
| `LinkType` | `LinkType` | — | Link type classification |
| `Rel` | `\[\]string` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `Attributes` | `map\[string\]string` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `Key` | `string` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `Value` | `string` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `map[string]string`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| --------------- | ---------- | ------- | ------------------------------------------------------- |
| `NodeType` | `NodeType` | — | Coarse-grained node type classification |
| `TagName` | `string` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `Depth` | `uint` | — | Depth in the DOM tree (0 = root) |
| `IndexInParent` | `uint` | — | Index among siblings (0-based) |
| `ParentTag` | `*string` | `nil` | Parent element’s tag name (None if root) |
| `IsInline` | `bool` | — | Whether this element is treated as inline vs block |
##### Methods
[Section titled “Methods”](#methods-2)
###### Attributes()
[Section titled “Attributes()”](#attributes-1)
Return a reference to the attribute map.
If the context was built with lazy attribute extraction, the map is materialized on the first call and cached for subsequent calls. If this method is never called, no allocation occurs for attributes.
**Signature:**
```go
func (o *NodeContext) Attributes() map[string]string
```
**Example:**
```go
result := instance.Attributes()
```
**Returns:** `map[string]string`
###### WithOwnedAttributes()
[Section titled “WithOwnedAttributes()”](#withownedattributes)
Construct a `NodeContext` with an owned attribute map.
Use this when the caller already has materialized attributes.
**Signature:**
```go
func NodeContextWithOwnedAttributes(nodeType NodeType, tagName string, attributes map[string]string, depth uint, indexInParent uint, parentTag string, isInline bool) *NodeContext
```
**Example:**
```go
result := NodeContextWithOwnedAttributes(NodeType{}, "value", nil, 42, 42, "value", true)
```
**Parameters:**
| Name | Type | Required | Description |
| --------------- | --------------------- | -------- | ------------------- |
| `NodeType` | `NodeType` | Yes | The node type |
| `TagName` | `string` | Yes | The tag name |
| `Attributes` | `map\[string\]string` | Yes | The attributes |
| `Depth` | `uint` | Yes | The depth |
| `IndexInParent` | `uint` | Yes | The index in parent |
| `ParentTag` | `*string` | No | The parent tag |
| `IsInline` | `bool` | Yes | The is inline |
**Returns:** `NodeContext`
###### IntoOwned()
[Section titled “IntoOwned()”](#intoowned)
Promote any borrowed fields into owned storage so the context can outlive `'a`.
**Signature:**
```go
func (o *NodeContext) IntoOwned() *NodeContext
```
**Example:**
```go
result := instance.IntoOwned()
```
**Returns:** `NodeContext`
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------ | --------------------- | ----------------------------- | -------------------------------------------------------------- |
| `Enabled` | `bool` | `true` | Enable HTML preprocessing globally |
| `Preset` | `PreprocessingPreset` | `PreprocessingPresetStandard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `RemoveNavigation` | `bool` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `RemoveForms` | `bool` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `Message` | `string` | — | Human-readable warning message. |
| `Kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | --------------------------------------------------------------- |
| `DataType` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `RawJSON` | `string` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `SchemaType` | `*string` | `nil` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `Grid` | `TableGrid` | — | The structured table grid. |
| `Markdown` | `string` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Rows` | `uint32` | — | Number of rows. |
| `Cols` | `uint32` | — | Number of columns. |
| `Cells` | `\[\]GridCell` | `nil` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `Start` | `uint32` | — | Start byte offset (inclusive) into the parent node’s text. |
| `End` | `uint32` | — | End byte offset (exclusive) into the parent node’s text. |
| `Kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------- | ---------------------------------------------------- |
| `LeftToRight` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Anchor` | Anchor link within same document (href starts with #) |
| `Internal` | Internal link within same domain |
| `External` | External link to different domain |
| `Email` | Email link (mailto:) |
| `Phone` | Phone link (tel:) |
| `Other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ----------- | -------------------------------------------------- |
| `DataURI` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | Inline SVG element |
| `External` | External image URL (http/https) |
| `Relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JSONLd` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `Rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `Tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `HTML` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### URLEscapeStyle
[Section titled “URLEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | A heading element (h1-h6). — Fields: `Level`: `uint8`, `Text`: `string` |
| `Paragraph` | A paragraph of text. — Fields: `Text`: `string` |
| `List` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `Ordered`: `bool` |
| `ListItem` | A single list item. — Fields: `Text`: `string` |
| `Table` | A table with structured cell data. — Fields: `Grid`: `TableGrid` |
| `Image` | An image element. — Fields: `Description`: `string`, `Src`: `string`, `ImageIndex`: `uint32` |
| `Code` | A code block or inline code. — Fields: `Text`: `string`, `Language`: `string` |
| `Quote` | A block quote container. |
| `DefinitionList` | A definition list container. |
| `DefinitionItem` | A definition list entry with term and description. — Fields: `Term`: `string`, `Definition`: `string` |
| `RawBlock` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `Format`: `string`, `Content`: `string` |
| `MetadataBlock` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `Entries`: `[]MetadataEntry` |
| `Group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `Label`: `string`, `HeadingLevel`: `uint8`, `HeadingText`: `string` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | Bold / strong emphasis. |
| `Italic` | Italic / emphasis. |
| `Underline` | Underline. |
| `Strikethrough` | Strikethrough / deleted text. |
| `Code` | Inline code. |
| `Subscript` | Subscript text. |
| `Superscript` | Superscript text. |
| `Highlight` | Highlighted / marked text. |
| `Link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `URL`: `string`, `Title`: `string` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | The input was truncated due to size limits. |
| `MalformedHTML` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ----------------------- | ---------------------------------------------- |
| `Text` | Text node (most frequent - 100+ per document) |
| `Element` | Generic element node |
| `Heading` | Heading elements (h1-h6) |
| `Paragraph` | Paragraph element |
| `Div` | Generic div container |
| `Blockquote` | Blockquote element |
| `Pre` | Preformatted text block |
| `Hr` | Horizontal rule |
| `List` | Ordered or unordered list (ul, ol) |
| `ListItem` | List item (li) |
| `DefinitionList` | Definition list (dl) |
| `DefinitionTerm` | Definition term (dt) |
| `DefinitionDescription` | Definition description (dd) |
| `Table` | Table element |
| `TableRow` | Table row (tr) |
| `TableCell` | Table cell (td, th) |
| `TableHeader` | Table header cell (th) |
| `TableBody` | Table body (tbody) |
| `TableHead` | Table head (thead) |
| `TableFoot` | Table foot (tfoot) |
| `Link` | Anchor link (a) |
| `Image` | Image (img) |
| `Strong` | Strong/bold (strong, b) |
| `Em` | Emphasis/italic (em, i) |
| `Code` | Inline code (code) |
| `Strikethrough` | Strikethrough (s, del, strike) |
| `Underline` | Underline (u, ins) |
| `Subscript` | Subscript (sub) |
| `Superscript` | Superscript (sup) |
| `Mark` | Mark/highlight (mark) |
| `Small` | Small text (small) |
| `Br` | Line break (br) |
| `Span` | Span element |
| `Article` | Article element |
| `Section` | Section element |
| `Nav` | Navigation element |
| `Aside` | Aside element |
| `Header` | Header element |
| `Footer` | Footer element |
| `Main` | Main element |
| `Figure` | Figure element |
| `Figcaption` | Figure caption |
| `Time` | Time element |
| `Details` | Details element |
| `Summary` | Summary element |
| `Form` | Form element |
| `Input` | Input element |
| `Select` | Select element |
| `Option` | Option element |
| `Button` | Button element |
| `Textarea` | Textarea element |
| `Label` | Label element |
| `Fieldset` | Fieldset element |
| `Legend` | Legend element |
| `Audio` | Audio element |
| `Video` | Video element |
| `Picture` | Picture element |
| `Source` | Source element |
| `Iframe` | Iframe element |
| `Svg` | SVG element |
| `Canvas` | Canvas element |
| `Ruby` | Ruby annotation |
| `Rt` | Ruby text |
| `Rp` | Ruby parenthesis |
| `Abbr` | Abbreviation |
| `Kbd` | Keyboard input |
| `Samp` | Sample output |
| `Var` | Variable |
| `Cite` | Citation |
| `Q` | Quote |
| `Del` | Deleted text |
| `Ins` | Inserted text |
| `Data` | Data element |
| `Meter` | Meter element |
| `Progress` | Progress element |
| `Output` | Output element |
| `Template` | Template element |
| `Slot` | Slot element |
| `HTML` | HTML root element |
| `Head` | Head element |
| `Body` | Body element |
| `Title` | Title element |
| `Meta` | Meta element |
| `LinkTag` | Link element (not anchor) |
| `Style` | Style element |
| `Script` | Script element |
| `Base` | Base element |
| `Custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Continue` | Continue with default conversion behavior |
| `Custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `string` |
| `Skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PreserveHTML` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `Error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `string` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ErrParseError` | HTML parsing error |
| `ErrSanitizationError` | HTML sanitization error |
| `ErrConfigError` | Invalid configuration |
| `ErrIoError` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `ErrPanic` | Internal error caught during conversion |
| `ErrInvalidInput` | Invalid input data |
| `ErrInputTooLarge` | Input exceeds the configured byte limit. |
| `ErrOther` | Generic conversion error |
***
# Java API Reference
## Java API Reference v3.17.2
[Section titled “Java API Reference v3.17.2”](#java-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```java
public static ConversionResult convert(String html, ConversionOptions options) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = convert("value", new ConversionOptions());
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ----------------------------- | -------- | ------------------ |
| `html` | `String` | Yes | The html |
| `options` | `@Nullable ConversionOptions` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Throws `HtmlToMarkdownRsException`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ---------------------------- | ------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `headingStyle` | `HeadingStyle` | `HeadingStyle.ATX` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `listIndentType` | `ListIndentType` | `ListIndentType.SPACES` | How to indent nested list items (spaces or tab). |
| `listIndentWidth` | `long` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `String` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strongEmSymbol` | `String` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escapeAsterisks` | `boolean` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escapeUnderscores` | `boolean` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escapeMisc` | `boolean` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escapeAscii` | `boolean` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `codeLanguage` | `String` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `boolean` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expandAbbreviations` | `boolean` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `includeBlockquoteCitations` | `boolean` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `defaultTitle` | `boolean` | `false` | Emit a default title when no `<title>` tag is present. |
| `brInTables` | `boolean` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compactTables` | `boolean` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlightStyle` | `HighlightStyle` | `HighlightStyle.DOUBLE_EQUAL` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extractMetadata` | `boolean` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespaceMode` | `WhitespaceMode` | `WhitespaceMode.NORMALIZED` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `stripNewlines` | `boolean` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `boolean` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrapWidth` | `long` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convertAsInline` | `boolean` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `subSymbol` | `String` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `supSymbol` | `String` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newlineStyle` | `NewlineStyle` | `NewlineStyle.SPACES` | How to encode hard line breaks (`<br>`) in Markdown. |
| `codeBlockStyle` | `CodeBlockStyle` | `CodeBlockStyle.BACKTICKS` | Style used for fenced code blocks (backticks or tilde). |
| `keepInlineImagesIn` | `List<String>` | `Collections.emptyList()` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `String` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `boolean` | `false` | Emit debug information during conversion. |
| `stripTags` | `List<String>` | `Collections.emptyList()` | HTML tag names whose content is stripped from the output entirely. |
| `preserveTags` | `List<String>` | `Collections.emptyList()` | HTML tag names that are preserved verbatim in the output. |
| `skipImages` | `boolean` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inlineDataMedia` | `InlineDataMedia` | `InlineDataMedia.KEEP` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hiddenContent` | `HiddenContent` | `HiddenContent.DROP` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `urlEscapeStyle` | `UrlEscapeStyle` | `UrlEscapeStyle.ANGLE` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `linkStyle` | `LinkStyle` | `LinkStyle.INLINE` | Link rendering style (inline or reference). |
| `outputFormat` | `OutputFormat` | `OutputFormat.MARKDOWN` | Target output format (Markdown, plain text, etc.). |
| `includeDocumentStructure` | `boolean` | `false` | Include structured document tree in result. |
| `extractImages` | `boolean` | `false` | Extract inline images from data URIs and SVGs. |
| `maxImageSize` | `long` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `maxInputSize` | `@Nullable Long` | `null` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `null`. Set `Some(bytes)` to choose another limit or `null` to disable it. |
| `captureSvg` | `boolean` | `false` | Capture SVG elements as images. |
| `inferDimensions` | `boolean` | `true` | Infer image dimensions from data. |
| `maxDepth` | `@Nullable Long` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `excludeSelectors` | `List<String>` | `Collections.emptyList()` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tierStrategy` | `TierStrategy` | `TierStrategy.AUTO` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `baseUrl` | `@Nullable String` | `null` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `null` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `@Nullable VisitorHandle` | `null` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | ----------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `@Nullable String` | `null` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `@Nullable DocumentStructure` | `null` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `null` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `List<TableData>` | `Collections.emptyList()` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `List<ProcessingWarning>` | `Collections.emptyList()` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| --------------- | ------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `@Nullable String` | `null` | Document title from `<title>` tag |
| `description` | `@Nullable String` | `null` | Document description from `<meta name="description">` tag |
| `keywords` | `List<String>` | `Collections.emptyList()` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `@Nullable String` | `null` | Document author from `<meta name="author">` tag |
| `canonicalUrl` | `@Nullable String` | `null` | Canonical URL from `<link rel="canonical">` tag |
| `baseHref` | `@Nullable String` | `null` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `@Nullable String` | `null` | Document language from `lang` attribute |
| `textDirection` | `@Nullable TextDirection` | `null` | Document text direction from `dir` attribute |
| `openGraph` | `Map<String, String>` | `Collections.emptyMap()` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitterCard` | `Map<String, String>` | `Collections.emptyMap()` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `metaTags` | `Map<String, String>` | `Collections.emptyMap()` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `String` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `@Nullable Integer` | `null` | Index of the parent node (None for root nodes). |
| `children` | `List<Integer>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `List<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `@Nullable Map<String, String>` | `null` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `null` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| -------------- | -------------------- | ------- | --------------------------------------------------- |
| `nodes` | `List<DocumentNode>` | — | All nodes in document reading order. |
| `sourceFormat` | `@Nullable String` | `null` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ---------- | --------- | ---------------------- | ---------------------------------------------- |
| `content` | `String` | — | The text content of the cell. |
| `row` | `int` | — | 0-indexed row position. |
| `col` | `int` | — | 0-indexed column position. |
| `rowSpan` | `int` | `1` | Number of rows this cell spans (default 1). |
| `colSpan` | `int` | `1` | Number of columns this cell spans (default 1). |
| `isHeader` | `boolean` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------ | ------------------ | ------- | ----------------------------------------- |
| `level` | `byte` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `String` | — | Normalized text content of the header |
| `id` | `@Nullable String` | `null` | HTML id attribute if present |
| `depth` | `long` | — | Document tree depth at the header element |
| `htmlOffset` | `long` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ---------------- | ---------------------- | ------------------------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `List<HeaderMetadata>` | `Collections.emptyList()` | Extracted header elements with hierarchy |
| `links` | `List<LinkMetadata>` | `Collections.emptyList()` | Extracted hyperlinks with type classification |
| `images` | `List<ImageMetadata>` | `Collections.emptyList()` | Extracted images with source and dimensions |
| `structuredData` | `List<StructuredData>` | `Collections.emptyList()` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### visitText()
[Section titled “visitText()”](#visittext)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```java
public VisitResult visitText(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitText(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitElementStart()
[Section titled “visitElementStart()”](#visitelementstart)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```java
public VisitResult visitElementStart(NodeContext ctx) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitElementStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitElementEnd()
[Section titled “visitElementEnd()”](#visitelementend)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```java
public VisitResult visitElementEnd(NodeContext ctx, String output) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitElementEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitLink()
[Section titled “visitLink()”](#visitlink)
Visit anchor links `<a href="...">`.
**Signature:**
```java
public VisitResult visitLink(NodeContext ctx, String href, String text, String title) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitLink(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `href` | `String` | Yes | The href |
| `text` | `String` | Yes | The text |
| `title` | `@Nullable String` | No | The title |
**Returns:** `VisitResult`
###### visitImage()
[Section titled “visitImage()”](#visitimage)
Visit images `<img src="...">`.
**Signature:**
```java
public VisitResult visitImage(NodeContext ctx, String src, String alt, String title) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitImage(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String` | Yes | The src |
| `alt` | `String` | Yes | The alt |
| `title` | `@Nullable String` | No | The title |
**Returns:** `VisitResult`
###### visitHeading()
[Section titled “visitHeading()”](#visitheading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```java
public VisitResult visitHeading(NodeContext ctx, int level, String text, String id) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitHeading(new NodeContext(), 42, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `level` | `int` | Yes | The level |
| `text` | `String` | Yes | The text |
| `id` | `@Nullable String` | No | The id |
**Returns:** `VisitResult`
###### visitCodeBlock()
[Section titled “visitCodeBlock()”](#visitcodeblock)
Visit code blocks `<pre><code>`.
**Signature:**
```java
public VisitResult visitCodeBlock(NodeContext ctx, String lang, String code) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitCodeBlock(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `lang` | `@Nullable String` | No | The lang |
| `code` | `String` | Yes | The code |
**Returns:** `VisitResult`
###### visitCodeInline()
[Section titled “visitCodeInline()”](#visitcodeinline)
Visit inline code `<code>`.
**Signature:**
```java
public VisitResult visitCodeInline(NodeContext ctx, String code) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitCodeInline(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `code` | `String` | Yes | The code |
**Returns:** `VisitResult`
###### visitListItem()
[Section titled “visitListItem()”](#visitlistitem)
Visit list items `<li>`.
**Signature:**
```java
public VisitResult visitListItem(NodeContext ctx, boolean ordered, String marker, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitListItem(new NodeContext(), true, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean` | Yes | The ordered |
| `marker` | `String` | Yes | The marker |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitListStart()
[Section titled “visitListStart()”](#visitliststart)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```java
public VisitResult visitListStart(NodeContext ctx, boolean ordered) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitListStart(new NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean` | Yes | The ordered |
**Returns:** `VisitResult`
###### visitListEnd()
[Section titled “visitListEnd()”](#visitlistend)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```java
public VisitResult visitListEnd(NodeContext ctx, boolean ordered, String output) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitListEnd(new NodeContext(), true, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean` | Yes | The ordered |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitTableStart()
[Section titled “visitTableStart()”](#visittablestart)
Called before processing a table `<table>`.
**Signature:**
```java
public VisitResult visitTableStart(NodeContext ctx) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitTableStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitTableRow()
[Section titled “visitTableRow()”](#visittablerow)
Visit table rows `<tr>`.
**Signature:**
```java
public VisitResult visitTableRow(NodeContext ctx, List<String> cells, boolean isHeader) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitTableRow(new NodeContext(), List.of(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | -------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `cells` | `List<String>` | Yes | The cells |
| `isHeader` | `boolean` | Yes | The is header |
**Returns:** `VisitResult`
###### visitTableEnd()
[Section titled “visitTableEnd()”](#visittableend)
Called after processing a table `</table>`.
**Signature:**
```java
public VisitResult visitTableEnd(NodeContext ctx, String output) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitTableEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitBlockquote()
[Section titled “visitBlockquote()”](#visitblockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```java
public VisitResult visitBlockquote(NodeContext ctx, String content, long depth) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitBlockquote(new NodeContext(), "value", 42);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `content` | `String` | Yes | The content |
| `depth` | `long` | Yes | The depth |
**Returns:** `VisitResult`
###### visitStrong()
[Section titled “visitStrong()”](#visitstrong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```java
public VisitResult visitStrong(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitStrong(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitEmphasis()
[Section titled “visitEmphasis()”](#visitemphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```java
public VisitResult visitEmphasis(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitEmphasis(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitStrikethrough()
[Section titled “visitStrikethrough()”](#visitstrikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```java
public VisitResult visitStrikethrough(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitStrikethrough(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitUnderline()
[Section titled “visitUnderline()”](#visitunderline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```java
public VisitResult visitUnderline(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitUnderline(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitSubscript()
[Section titled “visitSubscript()”](#visitsubscript)
Visit subscript elements `<sub>`.
**Signature:**
```java
public VisitResult visitSubscript(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitSubscript(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitSuperscript()
[Section titled “visitSuperscript()”](#visitsuperscript)
Visit superscript elements `<sup>`.
**Signature:**
```java
public VisitResult visitSuperscript(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitSuperscript(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitMark()
[Section titled “visitMark()”](#visitmark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```java
public VisitResult visitMark(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitMark(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitLineBreak()
[Section titled “visitLineBreak()”](#visitlinebreak)
Visit line break elements `<br>`.
**Signature:**
```java
public VisitResult visitLineBreak(NodeContext ctx) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitLineBreak(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitHorizontalRule()
[Section titled “visitHorizontalRule()”](#visithorizontalrule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```java
public VisitResult visitHorizontalRule(NodeContext ctx) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitHorizontalRule(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitCustomElement()
[Section titled “visitCustomElement()”](#visitcustomelement)
Visit custom elements (web components) or unknown tags.
**Signature:**
```java
public VisitResult visitCustomElement(NodeContext ctx, String tagName, String html) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitCustomElement(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `tagName` | `String` | Yes | The tag name |
| `html` | `String` | Yes | The html |
**Returns:** `VisitResult`
###### visitDefinitionListStart()
[Section titled “visitDefinitionListStart()”](#visitdefinitionliststart)
Visit definition list `<dl>`.
**Signature:**
```java
public VisitResult visitDefinitionListStart(NodeContext ctx) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitDefinitionListStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitDefinitionTerm()
[Section titled “visitDefinitionTerm()”](#visitdefinitionterm)
Visit definition term `<dt>`.
**Signature:**
```java
public VisitResult visitDefinitionTerm(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitDefinitionTerm(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionDescription()
[Section titled “visitDefinitionDescription()”](#visitdefinitiondescription)
Visit definition description `<dd>`.
**Signature:**
```java
public VisitResult visitDefinitionDescription(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitDefinitionDescription(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionListEnd()
[Section titled “visitDefinitionListEnd()”](#visitdefinitionlistend)
Called after processing a definition list `</dl>`.
**Signature:**
```java
public VisitResult visitDefinitionListEnd(NodeContext ctx, String output) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitDefinitionListEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitForm()
[Section titled “visitForm()”](#visitform)
Visit form elements `<form>`.
**Signature:**
```java
public VisitResult visitForm(NodeContext ctx, String action, String method) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitForm(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `action` | `@Nullable String` | No | The action |
| `method` | `@Nullable String` | No | The method |
**Returns:** `VisitResult`
###### visitInput()
[Section titled “visitInput()”](#visitinput)
Visit input elements `<input>`.
**Signature:**
```java
public VisitResult visitInput(NodeContext ctx, String inputType, String name, String value) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitInput(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `inputType` | `String` | Yes | The input type |
| `name` | `@Nullable String` | No | The name |
| `value` | `@Nullable String` | No | The value |
**Returns:** `VisitResult`
###### visitButton()
[Section titled “visitButton()”](#visitbutton)
Visit button elements `<button>`.
**Signature:**
```java
public VisitResult visitButton(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitButton(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitAudio()
[Section titled “visitAudio()”](#visitaudio)
Visit audio elements `<audio>`.
**Signature:**
```java
public VisitResult visitAudio(NodeContext ctx, String src) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitAudio(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `@Nullable String` | No | The src |
**Returns:** `VisitResult`
###### visitVideo()
[Section titled “visitVideo()”](#visitvideo)
Visit video elements `<video>`.
**Signature:**
```java
public VisitResult visitVideo(NodeContext ctx, String src) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitVideo(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `@Nullable String` | No | The src |
**Returns:** `VisitResult`
###### visitIframe()
[Section titled “visitIframe()”](#visitiframe)
Visit iframe elements `<iframe>`.
**Signature:**
```java
public VisitResult visitIframe(NodeContext ctx, String src) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitIframe(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------------ | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `@Nullable String` | No | The src |
**Returns:** `VisitResult`
###### visitDetails()
[Section titled “visitDetails()”](#visitdetails)
Visit details elements `<details>`.
**Signature:**
```java
public VisitResult visitDetails(NodeContext ctx, boolean open) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitDetails(new NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `open` | `boolean` | Yes | The open |
**Returns:** `VisitResult`
###### visitSummary()
[Section titled “visitSummary()”](#visitsummary)
Visit summary elements `<summary>`.
**Signature:**
```java
public VisitResult visitSummary(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitSummary(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureStart()
[Section titled “visitFigureStart()”](#visitfigurestart)
Visit figure elements `<figure>`.
**Signature:**
```java
public VisitResult visitFigureStart(NodeContext ctx) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitFigureStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitFigcaption()
[Section titled “visitFigcaption()”](#visitfigcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```java
public VisitResult visitFigcaption(NodeContext ctx, String text) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitFigcaption(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureEnd()
[Section titled “visitFigureEnd()”](#visitfigureend)
Called after processing a figure `</figure>`.
**Signature:**
```java
public VisitResult visitFigureEnd(NodeContext ctx, String output) throws HtmlToMarkdownRsException
```
**Example:**
```java
var result = instance.visitFigureEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `List<List<String>>` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ----- | ------- | ----------------- |
| `width` | `int` | — | Width in pixels. |
| `height` | `int` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | --------------------------- | ------- | ------------------------------------------------------- |
| `src` | `String` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `@Nullable String` | `null` | Alternative text from alt attribute (for accessibility) |
| `title` | `@Nullable String` | `null` | Title attribute (often shown as tooltip) |
| `dimensions` | `@Nullable ImageDimensions` | `null` | Image dimensions in pixels, if available. |
| `imageType` | `ImageType` | — | Image type classification |
| `attributes` | `Map<String, String>` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | --------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `String` | — | The href URL value |
| `text` | `String` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `@Nullable String` | `null` | Optional title attribute (often shown as tooltip) |
| `linkType` | `LinkType` | — | Link type classification |
| `rel` | `List<String>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `Map<String, String>` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `String` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `String` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `Map<String, String>`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| --------------- | ------------------ | ------- | ------------------------------------------------------- |
| `nodeType` | `NodeType` | — | Coarse-grained node type classification |
| `tagName` | `String` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `long` | — | Depth in the DOM tree (0 = root) |
| `indexInParent` | `long` | — | Index among siblings (0-based) |
| `parentTag` | `@Nullable String` | `null` | Parent element’s tag name (None if root) |
| `isInline` | `boolean` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------ | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `enabled` | `boolean` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset.STANDARD` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `removeNavigation` | `boolean` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `removeForms` | `boolean` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `String` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | --------------------------------------------------------------- |
| `dataType` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `rawJson` | `String` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schemaType` | `@Nullable String` | `null` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `String` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `int` | — | Number of rows. |
| `cols` | `int` | — | Number of columns. |
| `cells` | `List<GridCell>` | `Collections.emptyList()` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `int` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `int` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
##### Methods
[Section titled “Methods”](#methods-1)
###### close()
[Section titled “close()”](#close)
Releases the native handle backing this instance. Implements `AutoCloseable`; safe to call more than once.
**Signature:**
```java
public void close() throws HtmlToMarkdownRsException
```
**Example:**
```java
instance.close();
```
**Returns:** No return value.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| --------------- | ---------------------------------------------------- |
| `LEFT_TO_RIGHT` | Left-to-right text flow (default for Latin scripts) |
| `RIGHT_TO_LEFT` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `AUTO` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `ANCHOR` | Anchor link within same document (href starts with #) |
| `INTERNAL` | Internal link within same domain |
| `EXTERNAL` | External link to different domain |
| `EMAIL` | Email link (mailto:) |
| `PHONE` | Phone link (tel:) |
| `OTHER` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `DATA_URI` | Data URI embedded image (base64 or other encoding) |
| `INLINE_SVG` | Inline SVG element |
| `EXTERNAL` | External image URL (http/https) |
| `RELATIVE` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JSON_LD` | JSON-LD (JSON for Linking Data) script blocks |
| `MICRODATA` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `RDFA` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTO` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `TIER2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `TIER1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `MINIMAL` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `STANDARD` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `AGGRESSIVE` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `UNDERLINED` | Underlined style (=== for h1, — for h2). |
| `ATX` | ATX style (# for h1, ## for h2, etc.). Default. |
| `ATX_CLOSED` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `SPACES` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `TABS` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `NORMALIZED` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `STRICT` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `SPACES` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `BACKSLASH` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `INDENTED` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `BACKTICKS` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `TILDES` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| -------------- | ------------------------------------------------------------ |
| `DOUBLE_EQUAL` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `HTML` | Preserve as HTML (==text==). Original HTML tag. |
| `BOLD` | Render as bold (**text**). Uses strong emphasis. |
| `NONE` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `INLINE` | Inline links: `text`. Default. |
| `REFERENCE` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `ANGLE` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `PERCENT` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `KEEP` | Write the `data:` URL as the destination, payload included. Default. |
| `ALT_TEXT_ONLY` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DROP_ELEMENT` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DROP` | Drop the text a browser does not show at first. Default. |
| `REACHABLE` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `ALL` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `MARKDOWN` | Standard Markdown (`CommonMark` compatible). Default. |
| `DJOT` | Djot lightweight markup language. |
| `PLAIN` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HEADING` | A heading element (h1-h6). — Fields: `level`: `byte`, `text`: `String` |
| `PARAGRAPH` | A paragraph of text. — Fields: `text`: `String` |
| `LIST` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `boolean` |
| `LIST_ITEM` | A single list item. — Fields: `text`: `String` |
| `TABLE` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `IMAGE` | An image element. — Fields: `description`: `String`, `src`: `String`, `imageIndex`: `int` |
| `CODE` | A code block or inline code. — Fields: `text`: `String`, `language`: `String` |
| `QUOTE` | A block quote container. |
| `DEFINITION_LIST` | A definition list container. |
| `DEFINITION_ITEM` | A definition list entry with term and description. — Fields: `term`: `String`, `definition`: `String` |
| `RAW_BLOCK` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `String`, `content`: `String` |
| `METADATA_BLOCK` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `List<MetadataEntry>` |
| `GROUP` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `String`, `headingLevel`: `byte`, `headingText`: `String` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `BOLD` | Bold / strong emphasis. |
| `ITALIC` | Italic / emphasis. |
| `UNDERLINE` | Underline. |
| `STRIKETHROUGH` | Strikethrough / deleted text. |
| `CODE` | Inline code. |
| `SUBSCRIPT` | Subscript text. |
| `SUPERSCRIPT` | Superscript text. |
| `HIGHLIGHT` | Highlighted / marked text. |
| `LINK` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `String`, `title`: `String` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ------------------------- | ---------------------------------------------------------------------------- |
| `IMAGE_EXTRACTION_FAILED` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `ENCODING_FALLBACK` | The input encoding was not recognized; fell back to UTF-8. |
| `TRUNCATED_INPUT` | The input was truncated due to size limits. |
| `MALFORMED_HTML` | The HTML was malformed but processing continued with best effort. |
| `SANITIZATION_APPLIED` | Sanitization was applied to remove potentially unsafe content. |
| `DEPTH_LIMIT_EXCEEDED` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ------------------------ | ---------------------------------------------- |
| `TEXT` | Text node (most frequent - 100+ per document) |
| `ELEMENT` | Generic element node |
| `HEADING` | Heading elements (h1-h6) |
| `PARAGRAPH` | Paragraph element |
| `DIV` | Generic div container |
| `BLOCKQUOTE` | Blockquote element |
| `PRE` | Preformatted text block |
| `HR` | Horizontal rule |
| `LIST` | Ordered or unordered list (ul, ol) |
| `LIST_ITEM` | List item (li) |
| `DEFINITION_LIST` | Definition list (dl) |
| `DEFINITION_TERM` | Definition term (dt) |
| `DEFINITION_DESCRIPTION` | Definition description (dd) |
| `TABLE` | Table element |
| `TABLE_ROW` | Table row (tr) |
| `TABLE_CELL` | Table cell (td, th) |
| `TABLE_HEADER` | Table header cell (th) |
| `TABLE_BODY` | Table body (tbody) |
| `TABLE_HEAD` | Table head (thead) |
| `TABLE_FOOT` | Table foot (tfoot) |
| `LINK` | Anchor link (a) |
| `IMAGE` | Image (img) |
| `STRONG` | Strong/bold (strong, b) |
| `EM` | Emphasis/italic (em, i) |
| `CODE` | Inline code (code) |
| `STRIKETHROUGH` | Strikethrough (s, del, strike) |
| `UNDERLINE` | Underline (u, ins) |
| `SUBSCRIPT` | Subscript (sub) |
| `SUPERSCRIPT` | Superscript (sup) |
| `MARK` | Mark/highlight (mark) |
| `SMALL` | Small text (small) |
| `BR` | Line break (br) |
| `SPAN` | Span element |
| `ARTICLE` | Article element |
| `SECTION` | Section element |
| `NAV` | Navigation element |
| `ASIDE` | Aside element |
| `HEADER` | Header element |
| `FOOTER` | Footer element |
| `MAIN` | Main element |
| `FIGURE` | Figure element |
| `FIGCAPTION` | Figure caption |
| `TIME` | Time element |
| `DETAILS` | Details element |
| `SUMMARY` | Summary element |
| `FORM` | Form element |
| `INPUT` | Input element |
| `SELECT` | Select element |
| `OPTION` | Option element |
| `BUTTON` | Button element |
| `TEXTAREA` | Textarea element |
| `LABEL` | Label element |
| `FIELDSET` | Fieldset element |
| `LEGEND` | Legend element |
| `AUDIO` | Audio element |
| `VIDEO` | Video element |
| `PICTURE` | Picture element |
| `SOURCE` | Source element |
| `IFRAME` | Iframe element |
| `SVG` | SVG element |
| `CANVAS` | Canvas element |
| `RUBY` | Ruby annotation |
| `RT` | Ruby text |
| `RP` | Ruby parenthesis |
| `ABBR` | Abbreviation |
| `KBD` | Keyboard input |
| `SAMP` | Sample output |
| `VAR` | Variable |
| `CITE` | Citation |
| `Q` | Quote |
| `DEL` | Deleted text |
| `INS` | Inserted text |
| `DATA` | Data element |
| `METER` | Meter element |
| `PROGRESS` | Progress element |
| `OUTPUT` | Output element |
| `TEMPLATE` | Template element |
| `SLOT` | Slot element |
| `HTML` | HTML root element |
| `HEAD` | Head element |
| `BODY` | Body element |
| `TITLE` | Title element |
| `META` | Meta element |
| `LINK_TAG` | Link element (not anchor) |
| `STYLE` | Style element |
| `SCRIPT` | Script element |
| `BASE` | Base element |
| `CUSTOM` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTINUE` | Continue with default conversion behavior |
| `CUSTOM` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `String` |
| `SKIP` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PRESERVE_HTML` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `ERROR` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `String` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseErrorException` | HTML parsing error |
| `SanitizationErrorException` | HTML sanitization error |
| `ConfigErrorException` | Invalid configuration |
| `IoErrorException` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `PanicException` | Internal error caught during conversion |
| `InvalidInputException` | Invalid input data |
| `InputTooLargeException` | Input exceeds the configured byte limit. |
| `OtherException` | Generic conversion error |
***
# Kotlin (Android) API Reference
## Kotlin (Android) API Reference v3.17.2
[Section titled “Kotlin (Android) API Reference v3.17.2”](#kotlin-android-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```kotlin
@Throws(ConversionError::class)
fun convert(html: String, options: ConversionOptions? = null): ConversionResult
```
**Example:**
```kotlin
val result = convert("value", ConversionOptions())
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------------- | -------- | ------------------ |
| `html` | `String` | Yes | The html |
| `options` | `ConversionOptions?` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Throws `ConversionError`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ---------------------------- | ---------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `headingStyle` | `HeadingStyle` | `HeadingStyle.Atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `listIndentType` | `ListIndentType` | `ListIndentType.Spaces` | How to indent nested list items (spaces or tab). |
| `listIndentWidth` | `Long` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `String` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strongEmSymbol` | `String` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escapeAsterisks` | `Boolean` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escapeUnderscores` | `Boolean` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escapeMisc` | `Boolean` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escapeAscii` | `Boolean` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `codeLanguage` | `String` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `Boolean` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expandAbbreviations` | `Boolean` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `includeBlockquoteCitations` | `Boolean` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `defaultTitle` | `Boolean` | `false` | Emit a default title when no `<title>` tag is present. |
| `brInTables` | `Boolean` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compactTables` | `Boolean` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlightStyle` | `HighlightStyle` | `HighlightStyle.DoubleEqual` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extractMetadata` | `Boolean` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespaceMode` | `WhitespaceMode` | `WhitespaceMode.Normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `stripNewlines` | `Boolean` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `Boolean` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrapWidth` | `Long` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convertAsInline` | `Boolean` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `subSymbol` | `String` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `supSymbol` | `String` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newlineStyle` | `NewlineStyle` | `NewlineStyle.Spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `codeBlockStyle` | `CodeBlockStyle` | `CodeBlockStyle.Backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keepInlineImagesIn` | `List<String>` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `String` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `Boolean` | `false` | Emit debug information during conversion. |
| `stripTags` | `List<String>` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserveTags` | `List<String>` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skipImages` | `Boolean` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inlineDataMedia` | `InlineDataMedia` | `InlineDataMedia.Keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hiddenContent` | `HiddenContent` | `HiddenContent.Drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `urlEscapeStyle` | `UrlEscapeStyle` | `UrlEscapeStyle.Angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `linkStyle` | `LinkStyle` | `LinkStyle.Inline` | Link rendering style (inline or reference). |
| `outputFormat` | `OutputFormat` | `OutputFormat.Markdown` | Target output format (Markdown, plain text, etc.). |
| `includeDocumentStructure` | `Boolean` | `false` | Include structured document tree in result. |
| `extractImages` | `Boolean` | `false` | Extract inline images from data URIs and SVGs. |
| `maxImageSize` | `Long` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `maxInputSize` | `Long?` | `null` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `null`. Set `Some(bytes)` to choose another limit or `null` to disable it. |
| `captureSvg` | `Boolean` | `false` | Capture SVG elements as images. |
| `inferDimensions` | `Boolean` | `true` | Infer image dimensions from data. |
| `maxDepth` | `Long?` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `excludeSelectors` | `List<String>` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tierStrategy` | `TierStrategy` | `TierStrategy.Auto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `baseUrl` | `String?` | `null` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `null` — no resolution, output byte-identical to versions before this option existed. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `String?` | `null` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure?` | `null` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `null` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `List<TableData>` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `List<ProcessingWarning>` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| --------------- | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `String?` | `null` | Document title from `<title>` tag |
| `description` | `String?` | `null` | Document description from `<meta name="description">` tag |
| `keywords` | `List<String>` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `String?` | `null` | Document author from `<meta name="author">` tag |
| `canonicalUrl` | `String?` | `null` | Canonical URL from `<link rel="canonical">` tag |
| `baseHref` | `String?` | `null` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `String?` | `null` | Document language from `lang` attribute |
| `textDirection` | `TextDirection?` | `null` | Document text direction from `dir` attribute |
| `openGraph` | `Map<String, String>` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitterCard` | `Map<String, String>` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `metaTags` | `Map<String, String>` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ---------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `String` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `Int?` | `null` | Index of the parent node (None for root nodes). |
| `children` | `List<Int>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `List<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `Map<String, String>?` | `null` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `null` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| -------------- | -------------------- | ------- | --------------------------------------------------- |
| `nodes` | `List<DocumentNode>` | — | All nodes in document reading order. |
| `sourceFormat` | `String?` | `null` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ---------- | --------- | ---------------------- | ---------------------------------------------- |
| `content` | `String` | — | The text content of the cell. |
| `row` | `Int` | — | 0-indexed row position. |
| `col` | `Int` | — | 0-indexed column position. |
| `rowSpan` | `Int` | `1` | Number of rows this cell spans (default 1). |
| `colSpan` | `Int` | `1` | Number of columns this cell spans (default 1). |
| `isHeader` | `Boolean` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------ | --------- | ------- | ----------------------------------------- |
| `level` | `Byte` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `String` | — | Normalized text content of the header |
| `id` | `String?` | `null` | HTML id attribute if present |
| `depth` | `Long` | — | Document tree depth at the header element |
| `htmlOffset` | `Long` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ---------------- | ---------------------- | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `List<HeaderMetadata>` | `[]` | Extracted header elements with hierarchy |
| `links` | `List<LinkMetadata>` | `[]` | Extracted hyperlinks with type classification |
| `images` | `List<ImageMetadata>` | `[]` | Extracted images with source and dimensions |
| `structuredData` | `List<StructuredData>` | `[]` | Extracted structured data blocks |
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `List<List<String>>` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ----- | ------- | ----------------- |
| `width` | `Int` | — | Width in pixels. |
| `height` | `Int` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | --------------------- | ------- | ------------------------------------------------------- |
| `src` | `String` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `String?` | `null` | Alternative text from alt attribute (for accessibility) |
| `title` | `String?` | `null` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions?` | `null` | Image dimensions in pixels, if available. |
| `imageType` | `ImageType` | — | Image type classification |
| `attributes` | `Map<String, String>` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | --------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `String` | — | The href URL value |
| `text` | `String` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `String?` | `null` | Optional title attribute (often shown as tooltip) |
| `linkType` | `LinkType` | — | Link type classification |
| `rel` | `List<String>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `Map<String, String>` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `String` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `String` | — | Metadata value. |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------ | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `enabled` | `Boolean` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset.Standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `removeNavigation` | `Boolean` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `removeForms` | `Boolean` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `String` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | --------------------------------------------------------------- |
| `dataType` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `rawJson` | `String` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schemaType` | `String?` | `null` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `String` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `Int` | — | Number of rows. |
| `cols` | `Int` | — | Number of columns. |
| `cells` | `List<GridCell>` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `Int` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `Int` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------- | ---------------------------------------------------- |
| `LeftToRight` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Anchor` | Anchor link within same document (href starts with #) |
| `Internal` | Internal link within same domain |
| `External` | External link to different domain |
| `Email` | Email link (mailto:) |
| `Phone` | Phone link (tel:) |
| `Other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ----------- | -------------------------------------------------- |
| `DataUri` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | Inline SVG element |
| `External` | External image URL (http/https) |
| `Relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JsonLd` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `Rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `Tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | A heading element (h1-h6). — Fields: `level`: `Byte`, `text`: `String` |
| `Paragraph` | A paragraph of text. — Fields: `text`: `String` |
| `List` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `Boolean` |
| `ListItem` | A single list item. — Fields: `text`: `String` |
| `Table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `Image` | An image element. — Fields: `description`: `String`, `src`: `String`, `imageIndex`: `Int` |
| `Code` | A code block or inline code. — Fields: `text`: `String`, `language`: `String` |
| `Quote` | A block quote container. |
| `DefinitionList` | A definition list container. |
| `DefinitionItem` | A definition list entry with term and description. — Fields: `term`: `String`, `definition`: `String` |
| `RawBlock` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `String`, `content`: `String` |
| `MetadataBlock` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `List<MetadataEntry>` |
| `Group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `String`, `headingLevel`: `Byte`, `headingText`: `String` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | Bold / strong emphasis. |
| `Italic` | Italic / emphasis. |
| `Underline` | Underline. |
| `Strikethrough` | Strikethrough / deleted text. |
| `Code` | Inline code. |
| `Subscript` | Subscript text. |
| `Superscript` | Superscript text. |
| `Highlight` | Highlighted / marked text. |
| `Link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `String`, `title`: `String` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | The input was truncated due to size limits. |
| `MalformedHtml` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseError` | HTML parsing error |
| `SanitizationError` | HTML sanitization error |
| `ConfigError` | Invalid configuration |
| `IoError` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `Panic` | Internal error caught during conversion |
| `InvalidInput` | Invalid input data |
| `InputTooLarge` | Input exceeds the configured byte limit. |
| `Other` | Generic conversion error |
***
# PHP API Reference
## PHP API Reference v3.17.2
[Section titled “PHP API Reference v3.17.2”](#php-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown::convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```php
public static function convert(string $html, ?ConversionOptions $options = null): ConversionResult
```
**Example:**
```php
$result = convert("value", new ConversionOptions());
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------------- | -------- | ------------------ |
| `html` | `string` | Yes | The html |
| `options` | `?ConversionOptions` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Throws `ConversionError`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions::builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ---------------------------- | ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `headingStyle` | `HeadingStyle` | `HeadingStyle::ATX` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `listIndentType` | `ListIndentType` | `ListIndentType::SPACES` | How to indent nested list items (spaces or tab). |
| `listIndentWidth` | `int` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `string` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strongEmSymbol` | `string` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escapeAsterisks` | `bool` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escapeUnderscores` | `bool` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escapeMisc` | `bool` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escapeAscii` | `bool` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `codeLanguage` | `string` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `bool` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expandAbbreviations` | `bool` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `includeBlockquoteCitations` | `bool` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `defaultTitle` | `bool` | `false` | Emit a default title when no `<title>` tag is present. |
| `brInTables` | `bool` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compactTables` | `bool` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlightStyle` | `HighlightStyle` | `HighlightStyle::DOUBLEEQUAL` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extractMetadata` | `bool` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespaceMode` | `WhitespaceMode` | `WhitespaceMode::NORMALIZED` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode::Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode::Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `stripNewlines` | `bool` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `bool` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrapWidth` | `int` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convertAsInline` | `bool` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `subSymbol` | `string` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `supSymbol` | `string` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newlineStyle` | `NewlineStyle` | `NewlineStyle::SPACES` | How to encode hard line breaks (`<br>`) in Markdown. |
| `codeBlockStyle` | `CodeBlockStyle` | `CodeBlockStyle::BACKTICKS` | Style used for fenced code blocks (backticks or tilde). |
| `keepInlineImagesIn` | `array<string>` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions::builder`) to opt in or out of specific passes. |
| `encoding` | `string` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `bool` | `false` | Emit debug information during conversion. |
| `stripTags` | `array<string>` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserveTags` | `array<string>` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skipImages` | `bool` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inlineDataMedia` | `InlineDataMedia` | `InlineDataMedia::KEEP` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia::Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hiddenContent` | `HiddenContent` | `HiddenContent::DROP` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent::Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent::Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent::All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `urlEscapeStyle` | `UrlEscapeStyle` | `UrlEscapeStyle::ANGLE` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle::Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle::Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `linkStyle` | `LinkStyle` | `LinkStyle::INLINE` | Link rendering style (inline or reference). |
| `outputFormat` | `OutputFormat` | `OutputFormat::MARKDOWN` | Target output format (Markdown, plain text, etc.). |
| `includeDocumentStructure` | `bool` | `false` | Include structured document tree in result. |
| `extractImages` | `bool` | `false` | Extract inline images from data URIs and SVGs. |
| `maxImageSize` | `int` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `maxInputSize` | `?int` | `null` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `null`. Set `Some(bytes)` to choose another limit or `null` to disable it. |
| `captureSvg` | `bool` | `false` | Capture SVG elements as images. |
| `inferDimensions` | `bool` | `true` | Infer image dimensions from data. |
| `maxDepth` | `?int` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `excludeSelectors` | `array<string>` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tierStrategy` | `TierStrategy` | `TierStrategy::AUTO` | Which conversion tier to use. - `TierStrategy::Auto` (default) — automatically choose the best path. - `TierStrategy::Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy::Tier1` — always attempt Tier-1 (testkit only). |
| `baseUrl` | `?string` | `null` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `null` — no resolution, output byte-identical to versions before this option existed. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `?string` | `null` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `?DocumentStructure` | `null` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `null` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `array<TableData>` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self::document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self::content` as rendered Markdown. |
| `warnings` | `array<ProcessingWarning>` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| --------------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `?string` | `null` | Document title from `<title>` tag |
| `description` | `?string` | `null` | Document description from `<meta name="description">` tag |
| `keywords` | `array<string>` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `?string` | `null` | Document author from `<meta name="author">` tag |
| `canonicalUrl` | `?string` | `null` | Canonical URL from `<link rel="canonical">` tag |
| `baseHref` | `?string` | `null` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `?string` | `null` | Document language from `lang` attribute |
| `textDirection` | `?TextDirection` | `null` | Document text direction from `dir` attribute |
| `openGraph` | `array<string, string>` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitterCard` | `array<string, string>` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `metaTags` | `array<string, string>` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `?int` | `null` | Index of the parent node (None for root nodes). |
| `children` | `array<int>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `array<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `?array<string, string>` | `null` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `null` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| -------------- | --------------------- | ------- | --------------------------------------------------- |
| `nodes` | `array<DocumentNode>` | — | All nodes in document reading order. |
| `sourceFormat` | `?string` | `null` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ---------- | -------- | ---------------------- | ---------------------------------------------- |
| `content` | `string` | — | The text content of the cell. |
| `row` | `int` | — | 0-indexed row position. |
| `col` | `int` | — | 0-indexed column position. |
| `rowSpan` | `int` | `1` | Number of rows this cell spans (default 1). |
| `colSpan` | `int` | `1` | Number of columns this cell spans (default 1). |
| `isHeader` | `bool` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------ | --------- | ------- | ----------------------------------------- |
| `level` | `int` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `string` | — | Normalized text content of the header |
| `id` | `?string` | `null` | HTML id attribute if present |
| `depth` | `int` | — | Document tree depth at the header element |
| `htmlOffset` | `int` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ---------------- | ----------------------- | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `array<HeaderMetadata>` | `[]` | Extracted header elements with hierarchy |
| `links` | `array<LinkMetadata>` | `[]` | Extracted hyperlinks with type classification |
| `images` | `array<ImageMetadata>` | `[]` | Extracted images with source and dimensions |
| `structuredData` | `array<StructuredData>` | `[]` | Extracted structured data blocks |
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `array<array<string>>` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ----- | ------- | ----------------- |
| `width` | `int` | — | Width in pixels. |
| `height` | `int` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ----------------------- | ------- | ------------------------------------------------------- |
| `src` | `string` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `?string` | `null` | Alternative text from alt attribute (for accessibility) |
| `title` | `?string` | `null` | Title attribute (often shown as tooltip) |
| `dimensions` | `?ImageDimensions` | `null` | Image dimensions in pixels, if available. |
| `imageType` | `ImageType` | — | Image type classification |
| `attributes` | `array<string, string>` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ----------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `string` | — | The href URL value |
| `text` | `string` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `?string` | `null` | Optional title attribute (often shown as tooltip) |
| `linkType` | `LinkType` | — | Link type classification |
| `rel` | `array<string>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `array<string, string>` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent::MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `string` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `string` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext::attributes`, which returns `array<string, string>`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext::into_owned`.
| Field | Type | Default | Description |
| --------------- | ---------- | ------- | ------------------------------------------------------- |
| `nodeType` | `NodeType` | — | Coarse-grained node type classification |
| `tagName` | `string` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `int` | — | Depth in the DOM tree (0 = root) |
| `indexInParent` | `int` | — | Index among siblings (0-based) |
| `parentTag` | `?string` | `null` | Parent element’s tag name (None if root) |
| `isInline` | `bool` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------ | --------------------- | ------------------------------- | -------------------------------------------------------------- |
| `enabled` | `bool` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset::STANDARD` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `removeNavigation` | `bool` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `removeForms` | `bool` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `string` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | --------------------------------------------------------------- |
| `dataType` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `rawJson` | `string` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schemaType` | `?string` | `null` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `string` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `int` | — | Number of rows. |
| `cols` | `int` | — | Number of columns. |
| `cells` | `array<GridCell>` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode::content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `int` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `int` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------- | ---------------------------------------------------- |
| `LeftToRight` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Anchor` | Anchor link within same document (href starts with #) |
| `Internal` | Internal link within same domain |
| `External` | External link to different domain |
| `Email` | Email link (mailto:) |
| `Phone` | Phone link (tel:) |
| `Other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ----------- | -------------------------------------------------- |
| `DataUri` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | Inline SVG element |
| `External` | External image URL (http/https) |
| `Relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JsonLd` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `Rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | Always use the Tier-2 (`tl::parse` + walk) path, skipping Tier-1. |
| `Tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | A heading element (h1-h6). — Fields: `level`: `int`, `text`: `string` |
| `Paragraph` | A paragraph of text. — Fields: `text`: `string` |
| `List` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `bool` |
| `ListItem` | A single list item. — Fields: `text`: `string` |
| `Table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `Image` | An image element. — Fields: `description`: `string`, `src`: `string`, `imageIndex`: `int` |
| `Code` | A code block or inline code. — Fields: `text`: `string`, `language`: `string` |
| `Quote` | A block quote container. |
| `DefinitionList` | A definition list container. |
| `DefinitionItem` | A definition list entry with term and description. — Fields: `term`: `string`, `definition`: `string` |
| `RawBlock` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `string`, `content`: `string` |
| `MetadataBlock` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `array<MetadataEntry>` |
| `Group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `string`, `headingLevel`: `int`, `headingText`: `string` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | Bold / strong emphasis. |
| `Italic` | Italic / emphasis. |
| `Underline` | Underline. |
| `Strikethrough` | Strikethrough / deleted text. |
| `Code` | Inline code. |
| `Subscript` | Subscript text. |
| `Superscript` | Superscript text. |
| `Highlight` | Highlighted / marked text. |
| `Link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `string`, `title`: `string` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | The input was truncated due to size limits. |
| `MalformedHtml` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ----------------------- | ---------------------------------------------- |
| `Text` | Text node (most frequent - 100+ per document) |
| `Element` | Generic element node |
| `Heading` | Heading elements (h1-h6) |
| `Paragraph` | Paragraph element |
| `Div` | Generic div container |
| `Blockquote` | Blockquote element |
| `Pre` | Preformatted text block |
| `Hr` | Horizontal rule |
| `List` | Ordered or unordered list (ul, ol) |
| `ListItem` | List item (li) |
| `DefinitionList` | Definition list (dl) |
| `DefinitionTerm` | Definition term (dt) |
| `DefinitionDescription` | Definition description (dd) |
| `Table` | Table element |
| `TableRow` | Table row (tr) |
| `TableCell` | Table cell (td, th) |
| `TableHeader` | Table header cell (th) |
| `TableBody` | Table body (tbody) |
| `TableHead` | Table head (thead) |
| `TableFoot` | Table foot (tfoot) |
| `Link` | Anchor link (a) |
| `Image` | Image (img) |
| `Strong` | Strong/bold (strong, b) |
| `Em` | Emphasis/italic (em, i) |
| `Code` | Inline code (code) |
| `Strikethrough` | Strikethrough (s, del, strike) |
| `Underline` | Underline (u, ins) |
| `Subscript` | Subscript (sub) |
| `Superscript` | Superscript (sup) |
| `Mark` | Mark/highlight (mark) |
| `Small` | Small text (small) |
| `Br` | Line break (br) |
| `Span` | Span element |
| `Article` | Article element |
| `Section` | Section element |
| `Nav` | Navigation element |
| `Aside` | Aside element |
| `Header` | Header element |
| `Footer` | Footer element |
| `Main` | Main element |
| `Figure` | Figure element |
| `Figcaption` | Figure caption |
| `Time` | Time element |
| `Details` | Details element |
| `Summary` | Summary element |
| `Form` | Form element |
| `Input` | Input element |
| `Select` | Select element |
| `Option` | Option element |
| `Button` | Button element |
| `Textarea` | Textarea element |
| `Label` | Label element |
| `Fieldset` | Fieldset element |
| `Legend` | Legend element |
| `Audio` | Audio element |
| `Video` | Video element |
| `Picture` | Picture element |
| `Source` | Source element |
| `Iframe` | Iframe element |
| `Svg` | SVG element |
| `Canvas` | Canvas element |
| `Ruby` | Ruby annotation |
| `Rt` | Ruby text |
| `Rp` | Ruby parenthesis |
| `Abbr` | Abbreviation |
| `Kbd` | Keyboard input |
| `Samp` | Sample output |
| `Var` | Variable |
| `Cite` | Citation |
| `Q` | Quote |
| `Del` | Deleted text |
| `Ins` | Inserted text |
| `Data` | Data element |
| `Meter` | Meter element |
| `Progress` | Progress element |
| `Output` | Output element |
| `Template` | Template element |
| `Slot` | Slot element |
| `Html` | HTML root element |
| `Head` | Head element |
| `Body` | Body element |
| `Title` | Title element |
| `Meta` | Meta element |
| `LinkTag` | Link element (not anchor) |
| `Style` | Style element |
| `Script` | Script element |
| `Base` | Base element |
| `Custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Continue` | Continue with default conversion behavior |
| `Custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `string` |
| `Skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PreserveHtml` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `Error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `string` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ParseError` | HTML parsing error |
| `SanitizationError` | HTML sanitization error |
| `ConfigError` | Invalid configuration |
| `IoError` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError::from(io_error)` to convert from an operating-system I/O error. |
| `Panic` | Internal error caught during conversion |
| `InvalidInput` | Invalid input data |
| `InputTooLarge` | Input exceeds the configured byte limit. |
| `Other` | Generic conversion error |
***
# Python API Reference
## Python API Reference v3.17.2
[Section titled “Python API Reference v3.17.2”](#python-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```python
def convert(html: str, options: ConversionOptions = None) -> ConversionResult
```
**Example:**
```python
result = convert("value", options=ConversionOptions())
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------------------- | -------- | ------------------ |
| `html` | `str` | Yes | The html |
| `options` | `ConversionOptions \| None` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Raises `ConversionError`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ------------------------------ | ----------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading_style` | `HeadingStyle` | `HeadingStyle.ATX` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `list_indent_type` | `ListIndentType` | `ListIndentType.SPACES` | How to indent nested list items (spaces or tab). |
| `list_indent_width` | `int` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `str` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strong_em_symbol` | `str` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escape_asterisks` | `bool` | `False` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escape_underscores` | `bool` | `False` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escape_misc` | `bool` | `False` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escape_ascii` | `bool` | `False` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `code_language` | `str` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `bool` | `True` | Automatically convert bare URLs into Markdown autolinks. |
| `expand_abbreviations` | `bool` | `True` | Append the title of an `<abbr>` in parentheses (default `True`). |
| `include_blockquote_citations` | `bool` | `True` | Append the `cite` URL after a blockquote (default `True`). |
| `default_title` | `bool` | `False` | Emit a default title when no `<title>` tag is present. |
| `br_in_tables` | `bool` | `False` | Render `<br>` elements inside table cells as literal line breaks. |
| `compact_tables` | `bool` | `False` | Emit tables without column padding (compact GFM format). When `True`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `False` (aligned padding preserved). |
| `highlight_style` | `HighlightStyle` | `HighlightStyle.DOUBLE_EQUAL` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extract_metadata` | `bool` | `True` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `True`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespace_mode` | `WhitespaceMode` | `WhitespaceMode.NORMALIZED` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `strip_newlines` | `bool` | `False` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `bool` | `False` | Wrap long lines at `wrap_width` characters. |
| `wrap_width` | `int` | `80` | Maximum output line width in characters when `wrap` is `True` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `False`. |
| `convert_as_inline` | `bool` | `False` | Treat the entire document as inline content (no block-level wrappers). |
| `sub_symbol` | `str` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `sup_symbol` | `str` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newline_style` | `NewlineStyle` | `NewlineStyle.SPACES` | How to encode hard line breaks (`<br>`) in Markdown. |
| `code_block_style` | `CodeBlockStyle` | `CodeBlockStyle.BACKTICKS` | Style used for fenced code blocks (backticks or tilde). |
| `keep_inline_images_in` | `list\[str\]` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `str` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `bool` | `False` | Emit debug information during conversion. |
| `strip_tags` | `list\[str\]` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserve_tags` | `list\[str\]` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skip_images` | `bool` | `False` | Skip conversion of `<img>` elements (omit images from output). |
| `inline_data_media` | `InlineDataMedia` | `InlineDataMedia.KEEP` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hidden_content` | `HiddenContent` | `HiddenContent.DROP` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `url_escape_style` | `UrlEscapeStyle` | `UrlEscapeStyle.ANGLE` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `link_style` | `LinkStyle` | `LinkStyle.INLINE` | Link rendering style (inline or reference). |
| `output_format` | `OutputFormat` | `OutputFormat.MARKDOWN` | Target output format (Markdown, plain text, etc.). |
| `include_document_structure` | `bool` | `False` | Include structured document tree in result. |
| `extract_images` | `bool` | `False` | Extract inline images from data URIs and SVGs. |
| `max_image_size` | `int` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `max_input_size` | `int \| None` | `None` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `None`. Set `Some(bytes)` to choose another limit or `None` to disable it. |
| `capture_svg` | `bool` | `False` | Capture SVG elements as images. |
| `infer_dimensions` | `bool` | `True` | Infer image dimensions from data. |
| `max_depth` | `int \| None` | `None` | Maximum DOM traversal depth. `None` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `exclude_selectors` | `list\[str\]` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tier_strategy` | `TierStrategy` | `TierStrategy.AUTO` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `base_url` | `str \| None` | `None` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `None` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle \| None` | `None` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `str \| None` | `None` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure \| None` | `None` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `True`. `None` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `list\[TableData\]` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `True`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `list\[ProcessingWarning\]` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| ---------------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `str \| None` | `None` | Document title from `<title>` tag |
| `description` | `str \| None` | `None` | Document description from `<meta name="description">` tag |
| `keywords` | `list\[str\]` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `str \| None` | `None` | Document author from `<meta name="author">` tag |
| `canonical_url` | `str \| None` | `None` | Canonical URL from `<link rel="canonical">` tag |
| `base_href` | `str \| None` | `None` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `str \| None` | `None` | Document language from `lang` attribute |
| `text_direction` | `TextDirection \| None` | `None` | Document text direction from `dir` attribute |
| `open_graph` | `dict\[str, str\]` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitter_card` | `dict\[str, str\]` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `meta_tags` | `dict\[str, str\]` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | -------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `str` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `int \| None` | `None` | Index of the parent node (None for root nodes). |
| `children` | `list\[int\]` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `list\[TextAnnotation\]` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `dict\[str, str\] \| None` | `None` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `None` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| --------------- | ---------------------- | ------- | --------------------------------------------------- |
| `nodes` | `list\[DocumentNode\]` | — | All nodes in document reading order. |
| `source_format` | `str \| None` | `None` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ----------- | ------ | ---------------------- | ---------------------------------------------- |
| `content` | `str` | — | The text content of the cell. |
| `row` | `int` | — | 0-indexed row position. |
| `col` | `int` | — | 0-indexed column position. |
| `row_span` | `int` | `1` | Number of rows this cell spans (default 1). |
| `col_span` | `int` | `1` | Number of columns this cell spans (default 1). |
| `is_header` | `bool` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------- | ------------- | ------- | ----------------------------------------- |
| `level` | `int` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `str` | — | Normalized text content of the header |
| `id` | `str \| None` | `None` | HTML id attribute if present |
| `depth` | `int` | — | Document tree depth at the header element |
| `html_offset` | `int` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ----------------- | ------------------------ | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `list\[HeaderMetadata\]` | `[]` | Extracted header elements with hierarchy |
| `links` | `list\[LinkMetadata\]` | `[]` | Extracted hyperlinks with type classification |
| `images` | `list\[ImageMetadata\]` | `[]` | Extracted images with source and dimensions |
| `structured_data` | `list\[StructuredData\]` | `[]` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### visit_text()
[Section titled “visit_text()”](#visit_text)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```python
def visit_text(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_text(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_element_start()
[Section titled “visit_element_start()”](#visit_element_start)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```python
def visit_element_start(self, ctx: NodeContext) -> VisitResult
```
**Example:**
```python
result = instance.visit_element_start(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_element_end()
[Section titled “visit_element_end()”](#visit_element_end)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```python
def visit_element_end(self, ctx: NodeContext, output: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_element_end(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `str` | Yes | The output |
**Returns:** `VisitResult`
###### visit_link()
[Section titled “visit_link()”](#visit_link)
Visit anchor links `<a href="...">`.
**Signature:**
```python
def visit_link(self, ctx: NodeContext, href: str, text: str, title: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_link(NodeContext(), "value", "value", title="value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `href` | `str` | Yes | The href |
| `text` | `str` | Yes | The text |
| `title` | `str \| None` | No | The title |
**Returns:** `VisitResult`
###### visit_image()
[Section titled “visit_image()”](#visit_image)
Visit images `<img src="...">`.
**Signature:**
```python
def visit_image(self, ctx: NodeContext, src: str, alt: str, title: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_image(NodeContext(), "value", "value", title="value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `str` | Yes | The src |
| `alt` | `str` | Yes | The alt |
| `title` | `str \| None` | No | The title |
**Returns:** `VisitResult`
###### visit_heading()
[Section titled “visit_heading()”](#visit_heading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```python
def visit_heading(self, ctx: NodeContext, level: int, text: str, id: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_heading(NodeContext(), 42, "value", id="value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `level` | `int` | Yes | The level |
| `text` | `str` | Yes | The text |
| `id` | `str \| None` | No | The id |
**Returns:** `VisitResult`
###### visit_code_block()
[Section titled “visit_code_block()”](#visit_code_block)
Visit code blocks `<pre><code>`.
**Signature:**
```python
def visit_code_block(self, ctx: NodeContext, lang: str, code: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_code_block(NodeContext(), lang="value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `lang` | `str \| None` | No | The lang |
| `code` | `str` | Yes | The code |
**Returns:** `VisitResult`
###### visit_code_inline()
[Section titled “visit_code_inline()”](#visit_code_inline)
Visit inline code `<code>`.
**Signature:**
```python
def visit_code_inline(self, ctx: NodeContext, code: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_code_inline(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `code` | `str` | Yes | The code |
**Returns:** `VisitResult`
###### visit_list_item()
[Section titled “visit_list_item()”](#visit_list_item)
Visit list items `<li>`.
**Signature:**
```python
def visit_list_item(self, ctx: NodeContext, ordered: bool, marker: str, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_list_item(NodeContext(), True, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
| `marker` | `str` | Yes | The marker |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_list_start()
[Section titled “visit_list_start()”](#visit_list_start)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```python
def visit_list_start(self, ctx: NodeContext, ordered: bool) -> VisitResult
```
**Example:**
```python
result = instance.visit_list_start(NodeContext(), True)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
**Returns:** `VisitResult`
###### visit_list_end()
[Section titled “visit_list_end()”](#visit_list_end)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```python
def visit_list_end(self, ctx: NodeContext, ordered: bool, output: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_list_end(NodeContext(), True, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
| `output` | `str` | Yes | The output |
**Returns:** `VisitResult`
###### visit_table_start()
[Section titled “visit_table_start()”](#visit_table_start)
Called before processing a table `<table>`.
**Signature:**
```python
def visit_table_start(self, ctx: NodeContext) -> VisitResult
```
**Example:**
```python
result = instance.visit_table_start(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_table_row()
[Section titled “visit_table_row()”](#visit_table_row)
Visit table rows `<tr>`.
**Signature:**
```python
def visit_table_row(self, ctx: NodeContext, cells: list[str], is_header: bool) -> VisitResult
```
**Example:**
```python
result = instance.visit_table_row(NodeContext(), [], True)
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `cells` | `list\[str\]` | Yes | The cells |
| `is_header` | `bool` | Yes | The is header |
**Returns:** `VisitResult`
###### visit_table_end()
[Section titled “visit_table_end()”](#visit_table_end)
Called after processing a table `</table>`.
**Signature:**
```python
def visit_table_end(self, ctx: NodeContext, output: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_table_end(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `str` | Yes | The output |
**Returns:** `VisitResult`
###### visit_blockquote()
[Section titled “visit_blockquote()”](#visit_blockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```python
def visit_blockquote(self, ctx: NodeContext, content: str, depth: int) -> VisitResult
```
**Example:**
```python
result = instance.visit_blockquote(NodeContext(), "value", 42)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `content` | `str` | Yes | The content |
| `depth` | `int` | Yes | The depth |
**Returns:** `VisitResult`
###### visit_strong()
[Section titled “visit_strong()”](#visit_strong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```python
def visit_strong(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_strong(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_emphasis()
[Section titled “visit_emphasis()”](#visit_emphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```python
def visit_emphasis(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_emphasis(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_strikethrough()
[Section titled “visit_strikethrough()”](#visit_strikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```python
def visit_strikethrough(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_strikethrough(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_underline()
[Section titled “visit_underline()”](#visit_underline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```python
def visit_underline(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_underline(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_subscript()
[Section titled “visit_subscript()”](#visit_subscript)
Visit subscript elements `<sub>`.
**Signature:**
```python
def visit_subscript(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_subscript(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_superscript()
[Section titled “visit_superscript()”](#visit_superscript)
Visit superscript elements `<sup>`.
**Signature:**
```python
def visit_superscript(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_superscript(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_mark()
[Section titled “visit_mark()”](#visit_mark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```python
def visit_mark(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_mark(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_line_break()
[Section titled “visit_line_break()”](#visit_line_break)
Visit line break elements `<br>`.
**Signature:**
```python
def visit_line_break(self, ctx: NodeContext) -> VisitResult
```
**Example:**
```python
result = instance.visit_line_break(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_horizontal_rule()
[Section titled “visit_horizontal_rule()”](#visit_horizontal_rule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```python
def visit_horizontal_rule(self, ctx: NodeContext) -> VisitResult
```
**Example:**
```python
result = instance.visit_horizontal_rule(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_custom_element()
[Section titled “visit_custom_element()”](#visit_custom_element)
Visit custom elements (web components) or unknown tags.
**Signature:**
```python
def visit_custom_element(self, ctx: NodeContext, tag_name: str, html: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_custom_element(NodeContext(), "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `tag_name` | `str` | Yes | The tag name |
| `html` | `str` | Yes | The html |
**Returns:** `VisitResult`
###### visit_definition_list_start()
[Section titled “visit_definition_list_start()”](#visit_definition_list_start)
Visit definition list `<dl>`.
**Signature:**
```python
def visit_definition_list_start(self, ctx: NodeContext) -> VisitResult
```
**Example:**
```python
result = instance.visit_definition_list_start(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_definition_term()
[Section titled “visit_definition_term()”](#visit_definition_term)
Visit definition term `<dt>`.
**Signature:**
```python
def visit_definition_term(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_definition_term(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_description()
[Section titled “visit_definition_description()”](#visit_definition_description)
Visit definition description `<dd>`.
**Signature:**
```python
def visit_definition_description(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_definition_description(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_list_end()
[Section titled “visit_definition_list_end()”](#visit_definition_list_end)
Called after processing a definition list `</dl>`.
**Signature:**
```python
def visit_definition_list_end(self, ctx: NodeContext, output: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_definition_list_end(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `str` | Yes | The output |
**Returns:** `VisitResult`
###### visit_form()
[Section titled “visit_form()”](#visit_form)
Visit form elements `<form>`.
**Signature:**
```python
def visit_form(self, ctx: NodeContext, action: str, method: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_form(NodeContext(), action="value", method="value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `action` | `str \| None` | No | The action |
| `method` | `str \| None` | No | The method |
**Returns:** `VisitResult`
###### visit_input()
[Section titled “visit_input()”](#visit_input)
Visit input elements `<input>`.
**Signature:**
```python
def visit_input(self, ctx: NodeContext, input_type: str, name: str, value: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_input(NodeContext(), "value", name="value", value="value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `input_type` | `str` | Yes | The input type |
| `name` | `str \| None` | No | The name |
| `value` | `str \| None` | No | The value |
**Returns:** `VisitResult`
###### visit_button()
[Section titled “visit_button()”](#visit_button)
Visit button elements `<button>`.
**Signature:**
```python
def visit_button(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_button(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_audio()
[Section titled “visit_audio()”](#visit_audio)
Visit audio elements `<audio>`.
**Signature:**
```python
def visit_audio(self, ctx: NodeContext, src: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_audio(NodeContext(), src="value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `str \| None` | No | The src |
**Returns:** `VisitResult`
###### visit_video()
[Section titled “visit_video()”](#visit_video)
Visit video elements `<video>`.
**Signature:**
```python
def visit_video(self, ctx: NodeContext, src: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_video(NodeContext(), src="value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `str \| None` | No | The src |
**Returns:** `VisitResult`
###### visit_iframe()
[Section titled “visit_iframe()”](#visit_iframe)
Visit iframe elements `<iframe>`.
**Signature:**
```python
def visit_iframe(self, ctx: NodeContext, src: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_iframe(NodeContext(), src="value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `str \| None` | No | The src |
**Returns:** `VisitResult`
###### visit_details()
[Section titled “visit_details()”](#visit_details)
Visit details elements `<details>`.
**Signature:**
```python
def visit_details(self, ctx: NodeContext, open: bool) -> VisitResult
```
**Example:**
```python
result = instance.visit_details(NodeContext(), True)
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `open` | `bool` | Yes | The open |
**Returns:** `VisitResult`
###### visit_summary()
[Section titled “visit_summary()”](#visit_summary)
Visit summary elements `<summary>`.
**Signature:**
```python
def visit_summary(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_summary(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_start()
[Section titled “visit_figure_start()”](#visit_figure_start)
Visit figure elements `<figure>`.
**Signature:**
```python
def visit_figure_start(self, ctx: NodeContext) -> VisitResult
```
**Example:**
```python
result = instance.visit_figure_start(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_figcaption()
[Section titled “visit_figcaption()”](#visit_figcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```python
def visit_figcaption(self, ctx: NodeContext, text: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_figcaption(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_end()
[Section titled “visit_figure_end()”](#visit_figure_end)
Called after processing a figure `</figure>`.
**Signature:**
```python
def visit_figure_end(self, ctx: NodeContext, output: str) -> VisitResult
```
**Example:**
```python
result = instance.visit_figure_end(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `str` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `list[list[str]]` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ----- | ------- | ----------------- |
| `width` | `int` | — | Width in pixels. |
| `height` | `int` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ------------------------- | ------- | ------------------------------------------------------- |
| `src` | `str` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `str \| None` | `None` | Alternative text from alt attribute (for accessibility) |
| `title` | `str \| None` | `None` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions \| None` | `None` | Image dimensions in pixels, if available. |
| `image_type` | `ImageType` | — | Image type classification |
| `attributes` | `dict\[str, str\]` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ------------------ | ------- | ------------------------------------------------------------------- |
| `href` | `str` | — | The href URL value |
| `text` | `str` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `str \| None` | `None` | Optional title attribute (often shown as tooltip) |
| `link_type` | `LinkType` | — | Link type classification |
| `rel` | `list\[str\]` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `dict\[str, str\]` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | ----- | ------- | ------------------------------------------------------------- |
| `key` | `str` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `str` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `dict[str, str]`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| ----------------- | ------------- | ------- | ------------------------------------------------------- |
| `node_type` | `NodeType` | — | Coarse-grained node type classification |
| `tag_name` | `str` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `int` | — | Depth in the DOM tree (0 = root) |
| `index_in_parent` | `int` | — | Index among siblings (0-based) |
| `parent_tag` | `str \| None` | `None` | Parent element’s tag name (None if root) |
| `is_inline` | `bool` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------- | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `enabled` | `bool` | `True` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset.STANDARD` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `remove_navigation` | `bool` | `True` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `remove_forms` | `bool` | `True` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `str` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------- | -------------------- | ------- | --------------------------------------------------------------- |
| `data_type` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `raw_json` | `str` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schema_type` | `str \| None` | `None` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `str` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `int` | — | Number of rows. |
| `cols` | `int` | — | Number of columns. |
| `cells` | `list\[GridCell\]` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `int` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `int` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| --------------- | ---------------------------------------------------- |
| `LEFT_TO_RIGHT` | Left-to-right text flow (default for Latin scripts) |
| `RIGHT_TO_LEFT` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `AUTO` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `ANCHOR` | Anchor link within same document (href starts with #) |
| `INTERNAL` | Internal link within same domain |
| `EXTERNAL` | External link to different domain |
| `EMAIL` | Email link (mailto:) |
| `PHONE` | Phone link (tel:) |
| `OTHER` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `DATA_URI` | Data URI embedded image (base64 or other encoding) |
| `INLINE_SVG` | Inline SVG element |
| `EXTERNAL` | External image URL (http/https) |
| `RELATIVE` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JSON_LD` | JSON-LD (JSON for Linking Data) script blocks |
| `MICRODATA` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `RDFA` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTO` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `TIER2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `TIER1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `MINIMAL` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `STANDARD` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `AGGRESSIVE` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `UNDERLINED` | Underlined style (=== for h1, — for h2). |
| `ATX` | ATX style (# for h1, ## for h2, etc.). Default. |
| `ATX_CLOSED` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `SPACES` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `TABS` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `NORMALIZED` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `STRICT` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `SPACES` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `BACKSLASH` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `INDENTED` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `BACKTICKS` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `TILDES` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| -------------- | ------------------------------------------------------------ |
| `DOUBLE_EQUAL` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `HTML` | Preserve as HTML (==text==). Original HTML tag. |
| `BOLD` | Render as bold (**text**). Uses strong emphasis. |
| `NONE` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `INLINE` | Inline links: `text`. Default. |
| `REFERENCE` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `ANGLE` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `PERCENT` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `KEEP` | Write the `data:` URL as the destination, payload included. Default. |
| `ALT_TEXT_ONLY` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DROP_ELEMENT` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DROP` | Drop the text a browser does not show at first. Default. |
| `REACHABLE` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `ALL` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `MARKDOWN` | Standard Markdown (`CommonMark` compatible). Default. |
| `DJOT` | Djot lightweight markup language. |
| `PLAIN` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `HEADING` | A heading element (h1-h6). — Fields: `level`: `int`, `text`: `str` |
| `PARAGRAPH` | A paragraph of text. — Fields: `text`: `str` |
| `LIST` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `bool` |
| `LIST_ITEM` | A single list item. — Fields: `text`: `str` |
| `TABLE` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `IMAGE` | An image element. — Fields: `description`: `str`, `src`: `str`, `image_index`: `int` |
| `CODE` | A code block or inline code. — Fields: `text`: `str`, `language`: `str` |
| `QUOTE` | A block quote container. |
| `DEFINITION_LIST` | A definition list container. |
| `DEFINITION_ITEM` | A definition list entry with term and description. — Fields: `term`: `str`, `definition`: `str` |
| `RAW_BLOCK` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `str`, `content`: `str` |
| `METADATA_BLOCK` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `list[MetadataEntry]` |
| `GROUP` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `str`, `heading_level`: `int`, `heading_text`: `str` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------- |
| `BOLD` | Bold / strong emphasis. |
| `ITALIC` | Italic / emphasis. |
| `UNDERLINE` | Underline. |
| `STRIKETHROUGH` | Strikethrough / deleted text. |
| `CODE` | Inline code. |
| `SUBSCRIPT` | Subscript text. |
| `SUPERSCRIPT` | Superscript text. |
| `HIGHLIGHT` | Highlighted / marked text. |
| `LINK` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `str`, `title`: `str` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ------------------------- | ---------------------------------------------------------------------------- |
| `IMAGE_EXTRACTION_FAILED` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `ENCODING_FALLBACK` | The input encoding was not recognized; fell back to UTF-8. |
| `TRUNCATED_INPUT` | The input was truncated due to size limits. |
| `MALFORMED_HTML` | The HTML was malformed but processing continued with best effort. |
| `SANITIZATION_APPLIED` | Sanitization was applied to remove potentially unsafe content. |
| `DEPTH_LIMIT_EXCEEDED` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ------------------------ | ---------------------------------------------- |
| `TEXT` | Text node (most frequent - 100+ per document) |
| `ELEMENT` | Generic element node |
| `HEADING` | Heading elements (h1-h6) |
| `PARAGRAPH` | Paragraph element |
| `DIV` | Generic div container |
| `BLOCKQUOTE` | Blockquote element |
| `PRE` | Preformatted text block |
| `HR` | Horizontal rule |
| `LIST` | Ordered or unordered list (ul, ol) |
| `LIST_ITEM` | List item (li) |
| `DEFINITION_LIST` | Definition list (dl) |
| `DEFINITION_TERM` | Definition term (dt) |
| `DEFINITION_DESCRIPTION` | Definition description (dd) |
| `TABLE` | Table element |
| `TABLE_ROW` | Table row (tr) |
| `TABLE_CELL` | Table cell (td, th) |
| `TABLE_HEADER` | Table header cell (th) |
| `TABLE_BODY` | Table body (tbody) |
| `TABLE_HEAD` | Table head (thead) |
| `TABLE_FOOT` | Table foot (tfoot) |
| `LINK` | Anchor link (a) |
| `IMAGE` | Image (img) |
| `STRONG` | Strong/bold (strong, b) |
| `EM` | Emphasis/italic (em, i) |
| `CODE` | Inline code (code) |
| `STRIKETHROUGH` | Strikethrough (s, del, strike) |
| `UNDERLINE` | Underline (u, ins) |
| `SUBSCRIPT` | Subscript (sub) |
| `SUPERSCRIPT` | Superscript (sup) |
| `MARK` | Mark/highlight (mark) |
| `SMALL` | Small text (small) |
| `BR` | Line break (br) |
| `SPAN` | Span element |
| `ARTICLE` | Article element |
| `SECTION` | Section element |
| `NAV` | Navigation element |
| `ASIDE` | Aside element |
| `HEADER` | Header element |
| `FOOTER` | Footer element |
| `MAIN` | Main element |
| `FIGURE` | Figure element |
| `FIGCAPTION` | Figure caption |
| `TIME` | Time element |
| `DETAILS` | Details element |
| `SUMMARY` | Summary element |
| `FORM` | Form element |
| `INPUT` | Input element |
| `SELECT` | Select element |
| `OPTION` | Option element |
| `BUTTON` | Button element |
| `TEXTAREA` | Textarea element |
| `LABEL` | Label element |
| `FIELDSET` | Fieldset element |
| `LEGEND` | Legend element |
| `AUDIO` | Audio element |
| `VIDEO` | Video element |
| `PICTURE` | Picture element |
| `SOURCE` | Source element |
| `IFRAME` | Iframe element |
| `SVG` | SVG element |
| `CANVAS` | Canvas element |
| `RUBY` | Ruby annotation |
| `RT` | Ruby text |
| `RP` | Ruby parenthesis |
| `ABBR` | Abbreviation |
| `KBD` | Keyboard input |
| `SAMP` | Sample output |
| `VAR` | Variable |
| `CITE` | Citation |
| `Q` | Quote |
| `DEL` | Deleted text |
| `INS` | Inserted text |
| `DATA` | Data element |
| `METER` | Meter element |
| `PROGRESS` | Progress element |
| `OUTPUT` | Output element |
| `TEMPLATE` | Template element |
| `SLOT` | Slot element |
| `HTML` | HTML root element |
| `HEAD` | Head element |
| `BODY` | Body element |
| `TITLE` | Title element |
| `META` | Meta element |
| `LINK_TAG` | Link element (not anchor) |
| `STYLE` | Style element |
| `SCRIPT` | Script element |
| `BASE` | Base element |
| `CUSTOM` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `CONTINUE` | Continue with default conversion behavior |
| `CUSTOM` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `str` |
| `SKIP` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PRESERVE_HTML` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `ERROR` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `str` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
**Base class:** `ConversionError(Exception)`
| Exception | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseError(ConversionError)` | HTML parsing error |
| `SanitizationError(ConversionError)` | HTML sanitization error |
| `ConfigError(ConversionError)` | Invalid configuration |
| `IoError(ConversionError)` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `PanicError(ConversionError)` | Internal error caught during conversion |
| `InvalidInputError(ConversionError)` | Invalid input data |
| `InputTooLargeError(ConversionError)` | Input exceeds the configured byte limit. |
| `OtherError(ConversionError)` | Generic conversion error |
***
# R API Reference
## R API Reference v3.17.2
[Section titled “R API Reference v3.17.2”](#r-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```r
convert(html, options = NULL)
```
**Example:**
```r
result <- convert("value", %{})
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------------------- | -------- | ------------------ |
| `html` | `character` | Yes | The html |
| `options` | `ConversionOptions or NULL` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Stops with error message.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ------------------------------ | ----------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading_style` | `HeadingStyle` | `"atx"` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `list_indent_type` | `ListIndentType` | `"spaces"` | How to indent nested list items (spaces or tab). |
| `list_indent_width` | `integer` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `character` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strong_em_symbol` | `character` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escape_asterisks` | `logical` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escape_underscores` | `logical` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escape_misc` | `logical` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escape_ascii` | `logical` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `code_language` | `character` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `logical` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expand_abbreviations` | `logical` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `include_blockquote_citations` | `logical` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `default_title` | `logical` | `false` | Emit a default title when no `<title>` tag is present. |
| `br_in_tables` | `logical` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compact_tables` | `logical` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlight_style` | `HighlightStyle` | `"double_equal"` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extract_metadata` | `logical` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespace_mode` | `WhitespaceMode` | `"normalized"` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `strip_newlines` | `logical` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `logical` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrap_width` | `integer` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convert_as_inline` | `logical` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `sub_symbol` | `character` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `sup_symbol` | `character` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newline_style` | `NewlineStyle` | `"spaces"` | How to encode hard line breaks (`<br>`) in Markdown. |
| `code_block_style` | `CodeBlockStyle` | `"backticks"` | Style used for fenced code blocks (backticks or tilde). |
| `keep_inline_images_in` | `list` | `list()` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `character` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `logical` | `false` | Emit debug information during conversion. |
| `strip_tags` | `list` | `list()` | HTML tag names whose content is stripped from the output entirely. |
| `preserve_tags` | `list` | `list()` | HTML tag names that are preserved verbatim in the output. |
| `skip_images` | `logical` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inline_data_media` | `InlineDataMedia` | `"keep"` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hidden_content` | `HiddenContent` | `"drop"` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `url_escape_style` | `UrlEscapeStyle` | `"angle"` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `link_style` | `LinkStyle` | `"inline"` | Link rendering style (inline or reference). |
| `output_format` | `OutputFormat` | `"markdown"` | Target output format (Markdown, plain text, etc.). |
| `include_document_structure` | `logical` | `false` | Include structured document tree in result. |
| `extract_images` | `logical` | `false` | Extract inline images from data URIs and SVGs. |
| `max_image_size` | `integer` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `max_input_size` | `integer or NULL` | `NULL` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `NULL`. Set `Some(bytes)` to choose another limit or `NULL` to disable it. |
| `capture_svg` | `logical` | `false` | Capture SVG elements as images. |
| `infer_dimensions` | `logical` | `true` | Infer image dimensions from data. |
| `max_depth` | `integer or NULL` | `NULL` | Maximum DOM traversal depth. `NULL` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `exclude_selectors` | `list` | `list()` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tier_strategy` | `TierStrategy` | `"auto"` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `base_url` | `character or NULL` | `NULL` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `NULL` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle or NULL` | `NULL` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `character or NULL` | `NULL` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure or NULL` | `NULL` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `NULL` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `list` | `list()` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `list` | `list()` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| ---------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `character or NULL` | `NULL` | Document title from `<title>` tag |
| `description` | `character or NULL` | `NULL` | Document description from `<meta name="description">` tag |
| `keywords` | `list` | `list()` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `character or NULL` | `NULL` | Document author from `<meta name="author">` tag |
| `canonical_url` | `character or NULL` | `NULL` | Canonical URL from `<link rel="canonical">` tag |
| `base_href` | `character or NULL` | `NULL` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `character or NULL` | `NULL` | Document language from `lang` attribute |
| `text_direction` | `TextDirection or NULL` | `NULL` | Document text direction from `dir` attribute |
| `open_graph` | `list` | `list()` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitter_card` | `list` | `list()` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `meta_tags` | `list` | `list()` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ----------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `character` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `integer or NULL` | `NULL` | Index of the parent node (None for root nodes). |
| `children` | `list` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `list` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `list or NULL` | `NULL` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `NULL` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| --------------- | ------------------- | ------- | --------------------------------------------------- |
| `nodes` | `list` | — | All nodes in document reading order. |
| `source_format` | `character or NULL` | `NULL` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ----------- | ----------- | ---------------------- | ---------------------------------------------- |
| `content` | `character` | — | The text content of the cell. |
| `row` | `integer` | — | 0-indexed row position. |
| `col` | `integer` | — | 0-indexed column position. |
| `row_span` | `integer` | `1` | Number of rows this cell spans (default 1). |
| `col_span` | `integer` | `1` | Number of columns this cell spans (default 1). |
| `is_header` | `logical` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------- | ------------------- | ------- | ----------------------------------------- |
| `level` | `integer` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `character` | — | Normalized text content of the header |
| `id` | `character or NULL` | `NULL` | HTML id attribute if present |
| `depth` | `integer` | — | Document tree depth at the header element |
| `html_offset` | `integer` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ----------------- | ------------------ | -------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `list` | `list()` | Extracted header elements with hierarchy |
| `links` | `list` | `list()` | Extracted hyperlinks with type classification |
| `images` | `list` | `list()` | Extracted images with source and dimensions |
| `structured_data` | `list` | `list()` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### visit_text()
[Section titled “visit_text()”](#visit_text)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```r
visit_text(ctx, text)
```
**Example:**
```r
result <- instance.visit_text(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_element_start()
[Section titled “visit_element_start()”](#visit_element_start)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```r
visit_element_start(ctx)
```
**Example:**
```r
result <- instance.visit_element_start(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_element_end()
[Section titled “visit_element_end()”](#visit_element_end)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```r
visit_element_end(ctx, output)
```
**Example:**
```r
result <- instance.visit_element_end(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `character` | Yes | The output |
**Returns:** `VisitResult`
###### visit_link()
[Section titled “visit_link()”](#visit_link)
Visit anchor links `<a href="...">`.
**Signature:**
```r
visit_link(ctx, href, text, title)
```
**Example:**
```r
result <- instance.visit_link(%{}, "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `href` | `character` | Yes | The href |
| `text` | `character` | Yes | The text |
| `title` | `character or NULL` | No | The title |
**Returns:** `VisitResult`
###### visit_image()
[Section titled “visit_image()”](#visit_image)
Visit images `<img src="...">`.
**Signature:**
```r
visit_image(ctx, src, alt, title)
```
**Example:**
```r
result <- instance.visit_image(%{}, "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `character` | Yes | The src |
| `alt` | `character` | Yes | The alt |
| `title` | `character or NULL` | No | The title |
**Returns:** `VisitResult`
###### visit_heading()
[Section titled “visit_heading()”](#visit_heading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```r
visit_heading(ctx, level, text, id)
```
**Example:**
```r
result <- instance.visit_heading(%{}, 42, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `level` | `integer` | Yes | The level |
| `text` | `character` | Yes | The text |
| `id` | `character or NULL` | No | The id |
**Returns:** `VisitResult`
###### visit_code_block()
[Section titled “visit_code_block()”](#visit_code_block)
Visit code blocks `<pre><code>`.
**Signature:**
```r
visit_code_block(ctx, lang, code)
```
**Example:**
```r
result <- instance.visit_code_block(%{}, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `lang` | `character or NULL` | No | The lang |
| `code` | `character` | Yes | The code |
**Returns:** `VisitResult`
###### visit_code_inline()
[Section titled “visit_code_inline()”](#visit_code_inline)
Visit inline code `<code>`.
**Signature:**
```r
visit_code_inline(ctx, code)
```
**Example:**
```r
result <- instance.visit_code_inline(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `code` | `character` | Yes | The code |
**Returns:** `VisitResult`
###### visit_list_item()
[Section titled “visit_list_item()”](#visit_list_item)
Visit list items `<li>`.
**Signature:**
```r
visit_list_item(ctx, ordered, marker, text)
```
**Example:**
```r
result <- instance.visit_list_item(%{}, TRUE, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `logical` | Yes | The ordered |
| `marker` | `character` | Yes | The marker |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_list_start()
[Section titled “visit_list_start()”](#visit_list_start)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```r
visit_list_start(ctx, ordered)
```
**Example:**
```r
result <- instance.visit_list_start(%{}, TRUE)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `logical` | Yes | The ordered |
**Returns:** `VisitResult`
###### visit_list_end()
[Section titled “visit_list_end()”](#visit_list_end)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```r
visit_list_end(ctx, ordered, output)
```
**Example:**
```r
result <- instance.visit_list_end(%{}, TRUE, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `logical` | Yes | The ordered |
| `output` | `character` | Yes | The output |
**Returns:** `VisitResult`
###### visit_table_start()
[Section titled “visit_table_start()”](#visit_table_start)
Called before processing a table `<table>`.
**Signature:**
```r
visit_table_start(ctx)
```
**Example:**
```r
result <- instance.visit_table_start(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_table_row()
[Section titled “visit_table_row()”](#visit_table_row)
Visit table rows `<tr>`.
**Signature:**
```r
visit_table_row(ctx, cells, is_header)
```
**Example:**
```r
result <- instance.visit_table_row(%{}, [], TRUE)
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `cells` | `list` | Yes | The cells |
| `is_header` | `logical` | Yes | The is header |
**Returns:** `VisitResult`
###### visit_table_end()
[Section titled “visit_table_end()”](#visit_table_end)
Called after processing a table `</table>`.
**Signature:**
```r
visit_table_end(ctx, output)
```
**Example:**
```r
result <- instance.visit_table_end(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `character` | Yes | The output |
**Returns:** `VisitResult`
###### visit_blockquote()
[Section titled “visit_blockquote()”](#visit_blockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```r
visit_blockquote(ctx, content, depth)
```
**Example:**
```r
result <- instance.visit_blockquote(%{}, "value", 42)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `content` | `character` | Yes | The content |
| `depth` | `integer` | Yes | The depth |
**Returns:** `VisitResult`
###### visit_strong()
[Section titled “visit_strong()”](#visit_strong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```r
visit_strong(ctx, text)
```
**Example:**
```r
result <- instance.visit_strong(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_emphasis()
[Section titled “visit_emphasis()”](#visit_emphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```r
visit_emphasis(ctx, text)
```
**Example:**
```r
result <- instance.visit_emphasis(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_strikethrough()
[Section titled “visit_strikethrough()”](#visit_strikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```r
visit_strikethrough(ctx, text)
```
**Example:**
```r
result <- instance.visit_strikethrough(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_underline()
[Section titled “visit_underline()”](#visit_underline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```r
visit_underline(ctx, text)
```
**Example:**
```r
result <- instance.visit_underline(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_subscript()
[Section titled “visit_subscript()”](#visit_subscript)
Visit subscript elements `<sub>`.
**Signature:**
```r
visit_subscript(ctx, text)
```
**Example:**
```r
result <- instance.visit_subscript(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_superscript()
[Section titled “visit_superscript()”](#visit_superscript)
Visit superscript elements `<sup>`.
**Signature:**
```r
visit_superscript(ctx, text)
```
**Example:**
```r
result <- instance.visit_superscript(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_mark()
[Section titled “visit_mark()”](#visit_mark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```r
visit_mark(ctx, text)
```
**Example:**
```r
result <- instance.visit_mark(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_line_break()
[Section titled “visit_line_break()”](#visit_line_break)
Visit line break elements `<br>`.
**Signature:**
```r
visit_line_break(ctx)
```
**Example:**
```r
result <- instance.visit_line_break(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_horizontal_rule()
[Section titled “visit_horizontal_rule()”](#visit_horizontal_rule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```r
visit_horizontal_rule(ctx)
```
**Example:**
```r
result <- instance.visit_horizontal_rule(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_custom_element()
[Section titled “visit_custom_element()”](#visit_custom_element)
Visit custom elements (web components) or unknown tags.
**Signature:**
```r
visit_custom_element(ctx, tag_name, html)
```
**Example:**
```r
result <- instance.visit_custom_element(%{}, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `tag_name` | `character` | Yes | The tag name |
| `html` | `character` | Yes | The html |
**Returns:** `VisitResult`
###### visit_definition_list_start()
[Section titled “visit_definition_list_start()”](#visit_definition_list_start)
Visit definition list `<dl>`.
**Signature:**
```r
visit_definition_list_start(ctx)
```
**Example:**
```r
result <- instance.visit_definition_list_start(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_definition_term()
[Section titled “visit_definition_term()”](#visit_definition_term)
Visit definition term `<dt>`.
**Signature:**
```r
visit_definition_term(ctx, text)
```
**Example:**
```r
result <- instance.visit_definition_term(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_description()
[Section titled “visit_definition_description()”](#visit_definition_description)
Visit definition description `<dd>`.
**Signature:**
```r
visit_definition_description(ctx, text)
```
**Example:**
```r
result <- instance.visit_definition_description(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_list_end()
[Section titled “visit_definition_list_end()”](#visit_definition_list_end)
Called after processing a definition list `</dl>`.
**Signature:**
```r
visit_definition_list_end(ctx, output)
```
**Example:**
```r
result <- instance.visit_definition_list_end(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `character` | Yes | The output |
**Returns:** `VisitResult`
###### visit_form()
[Section titled “visit_form()”](#visit_form)
Visit form elements `<form>`.
**Signature:**
```r
visit_form(ctx, action, method)
```
**Example:**
```r
result <- instance.visit_form(%{}, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `action` | `character or NULL` | No | The action |
| `method` | `character or NULL` | No | The method |
**Returns:** `VisitResult`
###### visit_input()
[Section titled “visit_input()”](#visit_input)
Visit input elements `<input>`.
**Signature:**
```r
visit_input(ctx, input_type, name, value)
```
**Example:**
```r
result <- instance.visit_input(%{}, "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------------ | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `input_type` | `character` | Yes | The input type |
| `name` | `character or NULL` | No | The name |
| `value` | `character or NULL` | No | The value |
**Returns:** `VisitResult`
###### visit_button()
[Section titled “visit_button()”](#visit_button)
Visit button elements `<button>`.
**Signature:**
```r
visit_button(ctx, text)
```
**Example:**
```r
result <- instance.visit_button(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_audio()
[Section titled “visit_audio()”](#visit_audio)
Visit audio elements `<audio>`.
**Signature:**
```r
visit_audio(ctx, src)
```
**Example:**
```r
result <- instance.visit_audio(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `character or NULL` | No | The src |
**Returns:** `VisitResult`
###### visit_video()
[Section titled “visit_video()”](#visit_video)
Visit video elements `<video>`.
**Signature:**
```r
visit_video(ctx, src)
```
**Example:**
```r
result <- instance.visit_video(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `character or NULL` | No | The src |
**Returns:** `VisitResult`
###### visit_iframe()
[Section titled “visit_iframe()”](#visit_iframe)
Visit iframe elements `<iframe>`.
**Signature:**
```r
visit_iframe(ctx, src)
```
**Example:**
```r
result <- instance.visit_iframe(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `character or NULL` | No | The src |
**Returns:** `VisitResult`
###### visit_details()
[Section titled “visit_details()”](#visit_details)
Visit details elements `<details>`.
**Signature:**
```r
visit_details(ctx, open)
```
**Example:**
```r
result <- instance.visit_details(%{}, TRUE)
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `open` | `logical` | Yes | The open |
**Returns:** `VisitResult`
###### visit_summary()
[Section titled “visit_summary()”](#visit_summary)
Visit summary elements `<summary>`.
**Signature:**
```r
visit_summary(ctx, text)
```
**Example:**
```r
result <- instance.visit_summary(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_start()
[Section titled “visit_figure_start()”](#visit_figure_start)
Visit figure elements `<figure>`.
**Signature:**
```r
visit_figure_start(ctx)
```
**Example:**
```r
result <- instance.visit_figure_start(%{})
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_figcaption()
[Section titled “visit_figcaption()”](#visit_figcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```r
visit_figcaption(ctx, text)
```
**Example:**
```r
result <- instance.visit_figcaption(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `character` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_end()
[Section titled “visit_figure_end()”](#visit_figure_end)
Called after processing a figure `</figure>`.
**Signature:**
```r
visit_figure_end(ctx, output)
```
**Example:**
```r
result <- instance.visit_figure_end(%{}, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `character` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `list` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | --------- | ------- | ----------------- |
| `width` | `integer` | — | Width in pixels. |
| `height` | `integer` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ------------------------- | ------- | ------------------------------------------------------- |
| `src` | `character` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `character or NULL` | `NULL` | Alternative text from alt attribute (for accessibility) |
| `title` | `character or NULL` | `NULL` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions or NULL` | `NULL` | Image dimensions in pixels, if available. |
| `image_type` | `ImageType` | — | Image type classification |
| `attributes` | `list` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `character` | — | The href URL value |
| `text` | `character` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `character or NULL` | `NULL` | Optional title attribute (often shown as tooltip) |
| `link_type` | `LinkType` | — | Link type classification |
| `rel` | `list` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `list` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | ----------- | ------- | ------------------------------------------------------------- |
| `key` | `character` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `character` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `list`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| ----------------- | ------------------- | ------- | ------------------------------------------------------- |
| `node_type` | `NodeType` | — | Coarse-grained node type classification |
| `tag_name` | `character` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `integer` | — | Depth in the DOM tree (0 = root) |
| `index_in_parent` | `integer` | — | Index among siblings (0-based) |
| `parent_tag` | `character or NULL` | `NULL` | Parent element’s tag name (None if root) |
| `is_inline` | `logical` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------- | --------------------- | ------------ | -------------------------------------------------------------- |
| `enabled` | `logical` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `"standard"` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `remove_navigation` | `logical` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `remove_forms` | `logical` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `character` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------- | -------------------- | ------- | --------------------------------------------------------------- |
| `data_type` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `raw_json` | `character` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schema_type` | `character or NULL` | `NULL` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `character` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `integer` | — | Number of rows. |
| `cols` | `integer` | — | Number of columns. |
| `cells` | `list` | `list()` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `integer` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `integer` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| --------------- | ---------------------------------------------------- |
| `left_to_right` | Left-to-right text flow (default for Latin scripts) |
| `right_to_left` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `anchor` | Anchor link within same document (href starts with #) |
| `internal` | Internal link within same domain |
| `external` | External link to different domain |
| `email` | Email link (mailto:) |
| `phone` | Phone link (tel:) |
| `other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `data_uri` | Data URI embedded image (base64 or other encoding) |
| `inline_svg` | Inline SVG element |
| `external` | External image URL (http/https) |
| `relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `json_ld` | JSON-LD (JSON for Linking Data) script blocks |
| `microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `underlined` | Underlined style (=== for h1, — for h2). |
| `atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `atx_closed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| -------------- | ------------------------------------------------------------ |
| `double_equal` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `html` | Preserve as HTML (==text==). Original HTML tag. |
| `bold` | Render as bold (**text**). Uses strong emphasis. |
| `none` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `inline` | Inline links: `text`. Default. |
| `reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `keep` | Write the `data:` URL as the destination, payload included. Default. |
| `alt_text_only` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `drop_element` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `drop` | Drop the text a browser does not show at first. Default. |
| `reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `all` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `djot` | Djot lightweight markup language. |
| `plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading` | A heading element (h1-h6). — Fields: `level`: `integer`, `text`: `character` |
| `paragraph` | A paragraph of text. — Fields: `text`: `character` |
| `list` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `logical` |
| `list_item` | A single list item. — Fields: `text`: `character` |
| `table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `image` | An image element. — Fields: `description`: `character`, `src`: `character`, `image_index`: `integer` |
| `code` | A code block or inline code. — Fields: `text`: `character`, `language`: `character` |
| `quote` | A block quote container. |
| `definition_list` | A definition list container. |
| `definition_item` | A definition list entry with term and description. — Fields: `term`: `character`, `definition`: `character` |
| `raw_block` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `character`, `content`: `character` |
| `metadata_block` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `list` |
| `group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `character`, `heading_level`: `integer`, `heading_text`: `character` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| `bold` | Bold / strong emphasis. |
| `italic` | Italic / emphasis. |
| `underline` | Underline. |
| `strikethrough` | Strikethrough / deleted text. |
| `code` | Inline code. |
| `subscript` | Subscript text. |
| `superscript` | Superscript text. |
| `highlight` | Highlighted / marked text. |
| `link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `character`, `title`: `character` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ------------------------- | ---------------------------------------------------------------------------- |
| `image_extraction_failed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `encoding_fallback` | The input encoding was not recognized; fell back to UTF-8. |
| `truncated_input` | The input was truncated due to size limits. |
| `malformed_html` | The HTML was malformed but processing continued with best effort. |
| `sanitization_applied` | Sanitization was applied to remove potentially unsafe content. |
| `depth_limit_exceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ------------------------ | ---------------------------------------------- |
| `text` | Text node (most frequent - 100+ per document) |
| `element` | Generic element node |
| `heading` | Heading elements (h1-h6) |
| `paragraph` | Paragraph element |
| `div` | Generic div container |
| `blockquote` | Blockquote element |
| `pre` | Preformatted text block |
| `hr` | Horizontal rule |
| `list` | Ordered or unordered list (ul, ol) |
| `list_item` | List item (li) |
| `definition_list` | Definition list (dl) |
| `definition_term` | Definition term (dt) |
| `definition_description` | Definition description (dd) |
| `table` | Table element |
| `table_row` | Table row (tr) |
| `table_cell` | Table cell (td, th) |
| `table_header` | Table header cell (th) |
| `table_body` | Table body (tbody) |
| `table_head` | Table head (thead) |
| `table_foot` | Table foot (tfoot) |
| `link` | Anchor link (a) |
| `image` | Image (img) |
| `strong` | Strong/bold (strong, b) |
| `em` | Emphasis/italic (em, i) |
| `code` | Inline code (code) |
| `strikethrough` | Strikethrough (s, del, strike) |
| `underline` | Underline (u, ins) |
| `subscript` | Subscript (sub) |
| `superscript` | Superscript (sup) |
| `mark` | Mark/highlight (mark) |
| `small` | Small text (small) |
| `br` | Line break (br) |
| `span` | Span element |
| `article` | Article element |
| `section` | Section element |
| `nav` | Navigation element |
| `aside` | Aside element |
| `header` | Header element |
| `footer` | Footer element |
| `main` | Main element |
| `figure` | Figure element |
| `figcaption` | Figure caption |
| `time` | Time element |
| `details` | Details element |
| `summary` | Summary element |
| `form` | Form element |
| `input` | Input element |
| `select` | Select element |
| `option` | Option element |
| `button` | Button element |
| `textarea` | Textarea element |
| `label` | Label element |
| `fieldset` | Fieldset element |
| `legend` | Legend element |
| `audio` | Audio element |
| `video` | Video element |
| `picture` | Picture element |
| `source` | Source element |
| `iframe` | Iframe element |
| `svg` | SVG element |
| `canvas` | Canvas element |
| `ruby` | Ruby annotation |
| `rt` | Ruby text |
| `rp` | Ruby parenthesis |
| `abbr` | Abbreviation |
| `kbd` | Keyboard input |
| `samp` | Sample output |
| `var` | Variable |
| `cite` | Citation |
| `q` | Quote |
| `del` | Deleted text |
| `ins` | Inserted text |
| `data` | Data element |
| `meter` | Meter element |
| `progress` | Progress element |
| `output` | Output element |
| `template` | Template element |
| `slot` | Slot element |
| `html` | HTML root element |
| `head` | Head element |
| `body` | Body element |
| `title` | Title element |
| `meta` | Meta element |
| `link_tag` | Link element (not anchor) |
| `style` | Style element |
| `script` | Script element |
| `base` | Base element |
| `custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `continue` | Continue with default conversion behavior |
| `custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `character` |
| `skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `preserve_html` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `character` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parse_error` | HTML parsing error |
| `sanitization_error` | HTML sanitization error |
| `config_error` | Invalid configuration |
| `io_error` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `panic` | Internal error caught during conversion |
| `invalid_input` | Invalid input data |
| `input_too_large` | Input exceeds the configured byte limit. |
| `other` | Generic conversion error |
***
# Ruby API Reference
## Ruby API Reference v3.17.2
[Section titled “Ruby API Reference v3.17.2”](#ruby-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```ruby
def self.convert(html, options: nil)
```
**Example:**
```ruby
result = convert("value", options: ConversionOptions.new)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------------- | -------- | ------------------ |
| `html` | `String` | Yes | The html |
| `options` | `ConversionOptions?` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Raises `ConversionError`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ------------------------------ | ---------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading_style` | `HeadingStyle` | `:atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `list_indent_type` | `ListIndentType` | `:spaces` | How to indent nested list items (spaces or tab). |
| `list_indent_width` | `Integer` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `String` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strong_em_symbol` | `String` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escape_asterisks` | `Boolean` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escape_underscores` | `Boolean` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escape_misc` | `Boolean` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escape_ascii` | `Boolean` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `code_language` | `String` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `Boolean` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expand_abbreviations` | `Boolean` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `include_blockquote_citations` | `Boolean` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `default_title` | `Boolean` | `false` | Emit a default title when no `<title>` tag is present. |
| `br_in_tables` | `Boolean` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compact_tables` | `Boolean` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlight_style` | `HighlightStyle` | `:double_equal` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extract_metadata` | `Boolean` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespace_mode` | `WhitespaceMode` | `:normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `strip_newlines` | `Boolean` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `Boolean` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrap_width` | `Integer` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convert_as_inline` | `Boolean` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `sub_symbol` | `String` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `sup_symbol` | `String` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newline_style` | `NewlineStyle` | `:spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `code_block_style` | `CodeBlockStyle` | `:backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keep_inline_images_in` | `Array<String>` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `String` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `Boolean` | `false` | Emit debug information during conversion. |
| `strip_tags` | `Array<String>` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserve_tags` | `Array<String>` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skip_images` | `Boolean` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inline_data_media` | `InlineDataMedia` | `:keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hidden_content` | `HiddenContent` | `:drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `url_escape_style` | `UrlEscapeStyle` | `:angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `link_style` | `LinkStyle` | `:inline` | Link rendering style (inline or reference). |
| `output_format` | `OutputFormat` | `:markdown` | Target output format (Markdown, plain text, etc.). |
| `include_document_structure` | `Boolean` | `false` | Include structured document tree in result. |
| `extract_images` | `Boolean` | `false` | Extract inline images from data URIs and SVGs. |
| `max_image_size` | `Integer` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `max_input_size` | `Integer?` | `nil` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `nil`. Set `Some(bytes)` to choose another limit or `nil` to disable it. |
| `capture_svg` | `Boolean` | `false` | Capture SVG elements as images. |
| `infer_dimensions` | `Boolean` | `true` | Infer image dimensions from data. |
| `max_depth` | `Integer?` | `nil` | Maximum DOM traversal depth. `nil` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `exclude_selectors` | `Array<String>` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tier_strategy` | `TierStrategy` | `:auto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `base_url` | `String?` | `nil` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `nil` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle?` | `nil` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `String?` | `nil` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure?` | `nil` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `nil` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `Array<TableData>` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `Array<ProcessingWarning>` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| ---------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `String?` | `nil` | Document title from `<title>` tag |
| `description` | `String?` | `nil` | Document description from `<meta name="description">` tag |
| `keywords` | `Array<String>` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `String?` | `nil` | Document author from `<meta name="author">` tag |
| `canonical_url` | `String?` | `nil` | Canonical URL from `<link rel="canonical">` tag |
| `base_href` | `String?` | `nil` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `String?` | `nil` | Document language from `lang` attribute |
| `text_direction` | `TextDirection?` | `nil` | Document text direction from `dir` attribute |
| `open_graph` | `Hash{String=>String}` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitter_card` | `Hash{String=>String}` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `meta_tags` | `Hash{String=>String}` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ----------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `String` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `Integer?` | `nil` | Index of the parent node (None for root nodes). |
| `children` | `Array<Integer>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `Array<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `Hash{String=>String}?` | `nil` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `nil` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| --------------- | --------------------- | ------- | --------------------------------------------------- |
| `nodes` | `Array<DocumentNode>` | — | All nodes in document reading order. |
| `source_format` | `String?` | `nil` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ----------- | --------- | ---------------------- | ---------------------------------------------- |
| `content` | `String` | — | The text content of the cell. |
| `row` | `Integer` | — | 0-indexed row position. |
| `col` | `Integer` | — | 0-indexed column position. |
| `row_span` | `Integer` | `1` | Number of rows this cell spans (default 1). |
| `col_span` | `Integer` | `1` | Number of columns this cell spans (default 1). |
| `is_header` | `Boolean` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------- | --------- | ------- | ----------------------------------------- |
| `level` | `Integer` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `String` | — | Normalized text content of the header |
| `id` | `String?` | `nil` | HTML id attribute if present |
| `depth` | `Integer` | — | Document tree depth at the header element |
| `html_offset` | `Integer` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ----------------- | ----------------------- | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `Array<HeaderMetadata>` | `[]` | Extracted header elements with hierarchy |
| `links` | `Array<LinkMetadata>` | `[]` | Extracted hyperlinks with type classification |
| `images` | `Array<ImageMetadata>` | `[]` | Extracted images with source and dimensions |
| `structured_data` | `Array<StructuredData>` | `[]` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### visit_text()
[Section titled “visit_text()”](#visit_text)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```ruby
def visit_text(ctx, text)
```
**Example:**
```ruby
result = instance.visit_text(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_element_start()
[Section titled “visit_element_start()”](#visit_element_start)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```ruby
def visit_element_start(ctx)
```
**Example:**
```ruby
result = instance.visit_element_start(NodeContext.new)
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_element_end()
[Section titled “visit_element_end()”](#visit_element_end)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```ruby
def visit_element_end(ctx, output)
```
**Example:**
```ruby
result = instance.visit_element_end(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visit_link()
[Section titled “visit_link()”](#visit_link)
Visit anchor links `<a href="...">`.
**Signature:**
```ruby
def visit_link(ctx, href, text, title)
```
**Example:**
```ruby
result = instance.visit_link(NodeContext.new, "value", "value", title: "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `href` | `String` | Yes | The href |
| `text` | `String` | Yes | The text |
| `title` | `String?` | No | The title |
**Returns:** `VisitResult`
###### visit_image()
[Section titled “visit_image()”](#visit_image)
Visit images `<img src="...">`.
**Signature:**
```ruby
def visit_image(ctx, src, alt, title)
```
**Example:**
```ruby
result = instance.visit_image(NodeContext.new, "value", "value", title: "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String` | Yes | The src |
| `alt` | `String` | Yes | The alt |
| `title` | `String?` | No | The title |
**Returns:** `VisitResult`
###### visit_heading()
[Section titled “visit_heading()”](#visit_heading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```ruby
def visit_heading(ctx, level, text, id)
```
**Example:**
```ruby
result = instance.visit_heading(NodeContext.new, 42, "value", id: "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `level` | `Integer` | Yes | The level |
| `text` | `String` | Yes | The text |
| `id` | `String?` | No | The id |
**Returns:** `VisitResult`
###### visit_code_block()
[Section titled “visit_code_block()”](#visit_code_block)
Visit code blocks `<pre><code>`.
**Signature:**
```ruby
def visit_code_block(ctx, lang, code)
```
**Example:**
```ruby
result = instance.visit_code_block(NodeContext.new, lang: "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `lang` | `String?` | No | The lang |
| `code` | `String` | Yes | The code |
**Returns:** `VisitResult`
###### visit_code_inline()
[Section titled “visit_code_inline()”](#visit_code_inline)
Visit inline code `<code>`.
**Signature:**
```ruby
def visit_code_inline(ctx, code)
```
**Example:**
```ruby
result = instance.visit_code_inline(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `code` | `String` | Yes | The code |
**Returns:** `VisitResult`
###### visit_list_item()
[Section titled “visit_list_item()”](#visit_list_item)
Visit list items `<li>`.
**Signature:**
```ruby
def visit_list_item(ctx, ordered, marker, text)
```
**Example:**
```ruby
result = instance.visit_list_item(NodeContext.new, true, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `Boolean` | Yes | The ordered |
| `marker` | `String` | Yes | The marker |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_list_start()
[Section titled “visit_list_start()”](#visit_list_start)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```ruby
def visit_list_start(ctx, ordered)
```
**Example:**
```ruby
result = instance.visit_list_start(NodeContext.new, true)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `Boolean` | Yes | The ordered |
**Returns:** `VisitResult`
###### visit_list_end()
[Section titled “visit_list_end()”](#visit_list_end)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```ruby
def visit_list_end(ctx, ordered, output)
```
**Example:**
```ruby
result = instance.visit_list_end(NodeContext.new, true, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `Boolean` | Yes | The ordered |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visit_table_start()
[Section titled “visit_table_start()”](#visit_table_start)
Called before processing a table `<table>`.
**Signature:**
```ruby
def visit_table_start(ctx)
```
**Example:**
```ruby
result = instance.visit_table_start(NodeContext.new)
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_table_row()
[Section titled “visit_table_row()”](#visit_table_row)
Visit table rows `<tr>`.
**Signature:**
```ruby
def visit_table_row(ctx, cells, is_header)
```
**Example:**
```ruby
result = instance.visit_table_row(NodeContext.new, [], true)
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | --------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `cells` | `Array<String>` | Yes | The cells |
| `is_header` | `Boolean` | Yes | The is header |
**Returns:** `VisitResult`
###### visit_table_end()
[Section titled “visit_table_end()”](#visit_table_end)
Called after processing a table `</table>`.
**Signature:**
```ruby
def visit_table_end(ctx, output)
```
**Example:**
```ruby
result = instance.visit_table_end(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visit_blockquote()
[Section titled “visit_blockquote()”](#visit_blockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```ruby
def visit_blockquote(ctx, content, depth)
```
**Example:**
```ruby
result = instance.visit_blockquote(NodeContext.new, "value", 42)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `content` | `String` | Yes | The content |
| `depth` | `Integer` | Yes | The depth |
**Returns:** `VisitResult`
###### visit_strong()
[Section titled “visit_strong()”](#visit_strong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```ruby
def visit_strong(ctx, text)
```
**Example:**
```ruby
result = instance.visit_strong(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_emphasis()
[Section titled “visit_emphasis()”](#visit_emphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```ruby
def visit_emphasis(ctx, text)
```
**Example:**
```ruby
result = instance.visit_emphasis(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_strikethrough()
[Section titled “visit_strikethrough()”](#visit_strikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```ruby
def visit_strikethrough(ctx, text)
```
**Example:**
```ruby
result = instance.visit_strikethrough(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_underline()
[Section titled “visit_underline()”](#visit_underline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```ruby
def visit_underline(ctx, text)
```
**Example:**
```ruby
result = instance.visit_underline(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_subscript()
[Section titled “visit_subscript()”](#visit_subscript)
Visit subscript elements `<sub>`.
**Signature:**
```ruby
def visit_subscript(ctx, text)
```
**Example:**
```ruby
result = instance.visit_subscript(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_superscript()
[Section titled “visit_superscript()”](#visit_superscript)
Visit superscript elements `<sup>`.
**Signature:**
```ruby
def visit_superscript(ctx, text)
```
**Example:**
```ruby
result = instance.visit_superscript(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_mark()
[Section titled “visit_mark()”](#visit_mark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```ruby
def visit_mark(ctx, text)
```
**Example:**
```ruby
result = instance.visit_mark(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_line_break()
[Section titled “visit_line_break()”](#visit_line_break)
Visit line break elements `<br>`.
**Signature:**
```ruby
def visit_line_break(ctx)
```
**Example:**
```ruby
result = instance.visit_line_break(NodeContext.new)
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_horizontal_rule()
[Section titled “visit_horizontal_rule()”](#visit_horizontal_rule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```ruby
def visit_horizontal_rule(ctx)
```
**Example:**
```ruby
result = instance.visit_horizontal_rule(NodeContext.new)
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_custom_element()
[Section titled “visit_custom_element()”](#visit_custom_element)
Visit custom elements (web components) or unknown tags.
**Signature:**
```ruby
def visit_custom_element(ctx, tag_name, html)
```
**Example:**
```ruby
result = instance.visit_custom_element(NodeContext.new, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `tag_name` | `String` | Yes | The tag name |
| `html` | `String` | Yes | The html |
**Returns:** `VisitResult`
###### visit_definition_list_start()
[Section titled “visit_definition_list_start()”](#visit_definition_list_start)
Visit definition list `<dl>`.
**Signature:**
```ruby
def visit_definition_list_start(ctx)
```
**Example:**
```ruby
result = instance.visit_definition_list_start(NodeContext.new)
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_definition_term()
[Section titled “visit_definition_term()”](#visit_definition_term)
Visit definition term `<dt>`.
**Signature:**
```ruby
def visit_definition_term(ctx, text)
```
**Example:**
```ruby
result = instance.visit_definition_term(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_description()
[Section titled “visit_definition_description()”](#visit_definition_description)
Visit definition description `<dd>`.
**Signature:**
```ruby
def visit_definition_description(ctx, text)
```
**Example:**
```ruby
result = instance.visit_definition_description(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_list_end()
[Section titled “visit_definition_list_end()”](#visit_definition_list_end)
Called after processing a definition list `</dl>`.
**Signature:**
```ruby
def visit_definition_list_end(ctx, output)
```
**Example:**
```ruby
result = instance.visit_definition_list_end(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visit_form()
[Section titled “visit_form()”](#visit_form)
Visit form elements `<form>`.
**Signature:**
```ruby
def visit_form(ctx, action, method)
```
**Example:**
```ruby
result = instance.visit_form(NodeContext.new, action: "value", method: "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `action` | `String?` | No | The action |
| `method` | `String?` | No | The method |
**Returns:** `VisitResult`
###### visit_input()
[Section titled “visit_input()”](#visit_input)
Visit input elements `<input>`.
**Signature:**
```ruby
def visit_input(ctx, input_type, name, value)
```
**Example:**
```ruby
result = instance.visit_input(NodeContext.new, "value", name: "value", value: "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `input_type` | `String` | Yes | The input type |
| `name` | `String?` | No | The name |
| `value` | `String?` | No | The value |
**Returns:** `VisitResult`
###### visit_button()
[Section titled “visit_button()”](#visit_button)
Visit button elements `<button>`.
**Signature:**
```ruby
def visit_button(ctx, text)
```
**Example:**
```ruby
result = instance.visit_button(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_audio()
[Section titled “visit_audio()”](#visit_audio)
Visit audio elements `<audio>`.
**Signature:**
```ruby
def visit_audio(ctx, src)
```
**Example:**
```ruby
result = instance.visit_audio(NodeContext.new, src: "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String?` | No | The src |
**Returns:** `VisitResult`
###### visit_video()
[Section titled “visit_video()”](#visit_video)
Visit video elements `<video>`.
**Signature:**
```ruby
def visit_video(ctx, src)
```
**Example:**
```ruby
result = instance.visit_video(NodeContext.new, src: "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String?` | No | The src |
**Returns:** `VisitResult`
###### visit_iframe()
[Section titled “visit_iframe()”](#visit_iframe)
Visit iframe elements `<iframe>`.
**Signature:**
```ruby
def visit_iframe(ctx, src)
```
**Example:**
```ruby
result = instance.visit_iframe(NodeContext.new, src: "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String?` | No | The src |
**Returns:** `VisitResult`
###### visit_details()
[Section titled “visit_details()”](#visit_details)
Visit details elements `<details>`.
**Signature:**
```ruby
def visit_details(ctx, open)
```
**Example:**
```ruby
result = instance.visit_details(NodeContext.new, true)
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `open` | `Boolean` | Yes | The open |
**Returns:** `VisitResult`
###### visit_summary()
[Section titled “visit_summary()”](#visit_summary)
Visit summary elements `<summary>`.
**Signature:**
```ruby
def visit_summary(ctx, text)
```
**Example:**
```ruby
result = instance.visit_summary(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_start()
[Section titled “visit_figure_start()”](#visit_figure_start)
Visit figure elements `<figure>`.
**Signature:**
```ruby
def visit_figure_start(ctx)
```
**Example:**
```ruby
result = instance.visit_figure_start(NodeContext.new)
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_figcaption()
[Section titled “visit_figcaption()”](#visit_figcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```ruby
def visit_figcaption(ctx, text)
```
**Example:**
```ruby
result = instance.visit_figcaption(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_end()
[Section titled “visit_figure_end()”](#visit_figure_end)
Called after processing a figure `</figure>`.
**Signature:**
```ruby
def visit_figure_end(ctx, output)
```
**Example:**
```ruby
result = instance.visit_figure_end(NodeContext.new, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `Array<Array<String>>` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | --------- | ------- | ----------------- |
| `width` | `Integer` | — | Width in pixels. |
| `height` | `Integer` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ---------------------- | ------- | ------------------------------------------------------- |
| `src` | `String` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `String?` | `nil` | Alternative text from alt attribute (for accessibility) |
| `title` | `String?` | `nil` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions?` | `nil` | Image dimensions in pixels, if available. |
| `image_type` | `ImageType` | — | Image type classification |
| `attributes` | `Hash{String=>String}` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ---------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `String` | — | The href URL value |
| `text` | `String` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `String?` | `nil` | Optional title attribute (often shown as tooltip) |
| `link_type` | `LinkType` | — | Link type classification |
| `rel` | `Array<String>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `Hash{String=>String}` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `String` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `String` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `Hash{String=>String}`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| ----------------- | ---------- | ------- | ------------------------------------------------------- |
| `node_type` | `NodeType` | — | Coarse-grained node type classification |
| `tag_name` | `String` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `Integer` | — | Depth in the DOM tree (0 = root) |
| `index_in_parent` | `Integer` | — | Index among siblings (0-based) |
| `parent_tag` | `String?` | `nil` | Parent element’s tag name (None if root) |
| `is_inline` | `Boolean` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------- | --------------------- | ----------- | -------------------------------------------------------------- |
| `enabled` | `Boolean` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `:standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `remove_navigation` | `Boolean` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `remove_forms` | `Boolean` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `String` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------- | -------------------- | ------- | --------------------------------------------------------------- |
| `data_type` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `raw_json` | `String` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schema_type` | `String?` | `nil` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `String` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `Integer` | — | Number of rows. |
| `cols` | `Integer` | — | Number of columns. |
| `cells` | `Array<GridCell>` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `Integer` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `Integer` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| --------------- | ---------------------------------------------------- |
| `left_to_right` | Left-to-right text flow (default for Latin scripts) |
| `right_to_left` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `anchor` | Anchor link within same document (href starts with #) |
| `internal` | Internal link within same domain |
| `external` | External link to different domain |
| `email` | Email link (mailto:) |
| `phone` | Phone link (tel:) |
| `other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `data_uri` | Data URI embedded image (base64 or other encoding) |
| `inline_svg` | Inline SVG element |
| `external` | External image URL (http/https) |
| `relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `json_ld` | JSON-LD (JSON for Linking Data) script blocks |
| `microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `underlined` | Underlined style (=== for h1, — for h2). |
| `atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `atx_closed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| -------------- | ------------------------------------------------------------ |
| `double_equal` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `html` | Preserve as HTML (==text==). Original HTML tag. |
| `bold` | Render as bold (**text**). Uses strong emphasis. |
| `none` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `inline` | Inline links: `text`. Default. |
| `reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `keep` | Write the `data:` URL as the destination, payload included. Default. |
| `alt_text_only` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `drop_element` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `drop` | Drop the text a browser does not show at first. Default. |
| `reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `all` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `djot` | Djot lightweight markup language. |
| `plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading` | A heading element (h1-h6). — Fields: `level`: `Integer`, `text`: `String` |
| `paragraph` | A paragraph of text. — Fields: `text`: `String` |
| `list` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `Boolean` |
| `list_item` | A single list item. — Fields: `text`: `String` |
| `table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `image` | An image element. — Fields: `description`: `String`, `src`: `String`, `image_index`: `Integer` |
| `code` | A code block or inline code. — Fields: `text`: `String`, `language`: `String` |
| `quote` | A block quote container. |
| `definition_list` | A definition list container. |
| `definition_item` | A definition list entry with term and description. — Fields: `term`: `String`, `definition`: `String` |
| `raw_block` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `String`, `content`: `String` |
| `metadata_block` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `Array<MetadataEntry>` |
| `group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `String`, `heading_level`: `Integer`, `heading_text`: `String` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `bold` | Bold / strong emphasis. |
| `italic` | Italic / emphasis. |
| `underline` | Underline. |
| `strikethrough` | Strikethrough / deleted text. |
| `code` | Inline code. |
| `subscript` | Subscript text. |
| `superscript` | Superscript text. |
| `highlight` | Highlighted / marked text. |
| `link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `String`, `title`: `String` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ------------------------- | ---------------------------------------------------------------------------- |
| `image_extraction_failed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `encoding_fallback` | The input encoding was not recognized; fell back to UTF-8. |
| `truncated_input` | The input was truncated due to size limits. |
| `malformed_html` | The HTML was malformed but processing continued with best effort. |
| `sanitization_applied` | Sanitization was applied to remove potentially unsafe content. |
| `depth_limit_exceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ------------------------ | ---------------------------------------------- |
| `text` | Text node (most frequent - 100+ per document) |
| `element` | Generic element node |
| `heading` | Heading elements (h1-h6) |
| `paragraph` | Paragraph element |
| `div` | Generic div container |
| `blockquote` | Blockquote element |
| `pre` | Preformatted text block |
| `hr` | Horizontal rule |
| `list` | Ordered or unordered list (ul, ol) |
| `list_item` | List item (li) |
| `definition_list` | Definition list (dl) |
| `definition_term` | Definition term (dt) |
| `definition_description` | Definition description (dd) |
| `table` | Table element |
| `table_row` | Table row (tr) |
| `table_cell` | Table cell (td, th) |
| `table_header` | Table header cell (th) |
| `table_body` | Table body (tbody) |
| `table_head` | Table head (thead) |
| `table_foot` | Table foot (tfoot) |
| `link` | Anchor link (a) |
| `image` | Image (img) |
| `strong` | Strong/bold (strong, b) |
| `em` | Emphasis/italic (em, i) |
| `code` | Inline code (code) |
| `strikethrough` | Strikethrough (s, del, strike) |
| `underline` | Underline (u, ins) |
| `subscript` | Subscript (sub) |
| `superscript` | Superscript (sup) |
| `mark` | Mark/highlight (mark) |
| `small` | Small text (small) |
| `br` | Line break (br) |
| `span` | Span element |
| `article` | Article element |
| `section` | Section element |
| `nav` | Navigation element |
| `aside` | Aside element |
| `header` | Header element |
| `footer` | Footer element |
| `main` | Main element |
| `figure` | Figure element |
| `figcaption` | Figure caption |
| `time` | Time element |
| `details` | Details element |
| `summary` | Summary element |
| `form` | Form element |
| `input` | Input element |
| `select` | Select element |
| `option` | Option element |
| `button` | Button element |
| `textarea` | Textarea element |
| `label` | Label element |
| `fieldset` | Fieldset element |
| `legend` | Legend element |
| `audio` | Audio element |
| `video` | Video element |
| `picture` | Picture element |
| `source` | Source element |
| `iframe` | Iframe element |
| `svg` | SVG element |
| `canvas` | Canvas element |
| `ruby` | Ruby annotation |
| `rt` | Ruby text |
| `rp` | Ruby parenthesis |
| `abbr` | Abbreviation |
| `kbd` | Keyboard input |
| `samp` | Sample output |
| `var` | Variable |
| `cite` | Citation |
| `q` | Quote |
| `del` | Deleted text |
| `ins` | Inserted text |
| `data` | Data element |
| `meter` | Meter element |
| `progress` | Progress element |
| `output` | Output element |
| `template` | Template element |
| `slot` | Slot element |
| `html` | HTML root element |
| `head` | Head element |
| `body` | Body element |
| `title` | Title element |
| `meta` | Meta element |
| `link_tag` | Link element (not anchor) |
| `style` | Style element |
| `script` | Script element |
| `base` | Base element |
| `custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `continue` | Continue with default conversion behavior |
| `custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `String` |
| `skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `preserve_html` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `String` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parse_error` | HTML parsing error |
| `sanitization_error` | HTML sanitization error |
| `config_error` | Invalid configuration |
| `io_error` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `panic` | Internal error caught during conversion |
| `invalid_input` | Invalid input data |
| `input_too_large` | Input exceeds the configured byte limit. |
| `other` | Generic conversion error |
***
# Rust API Reference
## Rust API Reference v3.17.2
[Section titled “Rust API Reference v3.17.2”](#rust-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown::convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```rust
pub fn convert(html: &str, options: Option<ConversionOptions>) -> Result<ConversionResult, ConversionError>
```
**Example:**
```rust
use html_to_markdown_rs::{convert, ConversionOptions};
let html = "<h1>Hello World</h1>";
// Bare options — most ergonomic.
let result = convert(html, ConversionOptions::default()).unwrap();
assert!(result.content.as_deref().unwrap_or("").contains("Hello World"));
// `None` falls back to defaults.
let result = convert(html, None).unwrap();
assert!(result.content.as_deref().unwrap_or("").contains("Hello World"));
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------------------- | -------- | ------------------ |
| `html` | `&str` | Yes | The html |
| `options` | `Option<ConversionOptions>` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Returns `Err(ConversionError)`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions::builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ------------------------------ | ----------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading_style` | `HeadingStyle` | `HeadingStyle::Atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `list_indent_type` | `ListIndentType` | `ListIndentType::Spaces` | How to indent nested list items (spaces or tab). |
| `list_indent_width` | `usize` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `String` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strong_em_symbol` | `String` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escape_asterisks` | `bool` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escape_underscores` | `bool` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escape_misc` | `bool` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escape_ascii` | `bool` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `code_language` | `String` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `bool` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expand_abbreviations` | `bool` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `include_blockquote_citations` | `bool` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `default_title` | `bool` | `false` | Emit a default title when no `<title>` tag is present. |
| `br_in_tables` | `bool` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compact_tables` | `bool` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlight_style` | `HighlightStyle` | `HighlightStyle::DoubleEqual` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extract_metadata` | `bool` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespace_mode` | `WhitespaceMode` | `WhitespaceMode::Normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode::Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode::Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `strip_newlines` | `bool` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `bool` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrap_width` | `usize` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convert_as_inline` | `bool` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `sub_symbol` | `String` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `sup_symbol` | `String` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newline_style` | `NewlineStyle` | `NewlineStyle::Spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `code_block_style` | `CodeBlockStyle` | `CodeBlockStyle::Backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keep_inline_images_in` | `Vec<String>` | `vec![]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to `PreprocessingOptions::default()`, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions::builder`) to opt in or out of specific passes. |
| `encoding` | `String` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `bool` | `false` | Emit debug information during conversion. |
| `strip_tags` | `Vec<String>` | `vec![]` | HTML tag names whose content is stripped from the output entirely. |
| `preserve_tags` | `Vec<String>` | `vec![]` | HTML tag names that are preserved verbatim in the output. |
| `skip_images` | `bool` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inline_data_media` | `InlineDataMedia` | `InlineDataMedia::Keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia::Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hidden_content` | `HiddenContent` | `HiddenContent::Drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent::Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent::Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent::All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `url_escape_style` | `UrlEscapeStyle` | `UrlEscapeStyle::Angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle::Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle::Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `link_style` | `LinkStyle` | `LinkStyle::Inline` | Link rendering style (inline or reference). |
| `output_format` | `OutputFormat` | `OutputFormat::Markdown` | Target output format (Markdown, plain text, etc.). |
| `include_document_structure` | `bool` | `false` | Include structured document tree in result. |
| `extract_images` | `bool` | `false` | Extract inline images from data URIs and SVGs. |
| `max_image_size` | `u64` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `max_input_size` | `Option<u64>` | `None` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `None`. Set `Some(bytes)` to choose another limit or `None` to disable it. |
| `capture_svg` | `bool` | `false` | Capture SVG elements as images. |
| `infer_dimensions` | `bool` | `true` | Infer image dimensions from data. |
| `max_depth` | `Option<usize>` | `None` | Maximum DOM traversal depth. `None` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `exclude_selectors` | `Vec<String>` | `vec![]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `vec![".cookie-banner".into(), "#ad-container".into(), "[role='complementary']".into()]` |
| `tier_strategy` | `TierStrategy` | `TierStrategy::Auto` | Which conversion tier to use. - `TierStrategy::Auto` (default) — automatically choose the best path. - `TierStrategy::Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy::Tier1` — always attempt Tier-1 (testkit only). |
| `base_url` | `Option<String>` | `None` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `None` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `Option<VisitorHandle>` | `None` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
##### Methods
[Section titled “Methods”](#methods)
###### default()
[Section titled “default()”](#default)
**Signature:**
```rust
pub fn default() -> ConversionOptions
```
**Example:**
```rust
let result = ConversionOptions::default();
```
**Returns:** `ConversionOptions`
***
#### ConversionOptionsBuilder
[Section titled “ConversionOptionsBuilder”](#conversionoptionsbuilder)
Builder for `ConversionOptions`.
All fields start with default values. Call `.build()` to produce the final options.
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `content` | `Option<String>` | `Default::default()` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `Option<DocumentStructure>` | `Default::default()` | Structured document tree with semantic elements. Populated when `ConversionOptions::include_document_structure` is `true`. `None` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in `Self::tables`. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `Vec<TableData>` | `vec![]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self::document`, so it is populated only when `ConversionOptions::include_document_structure` is `true`. With the default options this is an empty vec even for input that contains tables — the tables still appear in `Self::content` as rendered Markdown. |
| `images` | `Vec<InlineImage>` | `vec![]` | Extracted inline images from data URIs and SVGs. Populated when the `inline-images` feature is enabled and `extract_images` is `true`. Bindings may expose a simplified image representation or omit this Rust-only payload depending on backend support for binary image data. |
| `warnings` | `Vec<ProcessingWarning>` | `vec![]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| ---------------- | ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `Option<String>` | `Default::default()` | Document title from `<title>` tag |
| `description` | `Option<String>` | `Default::default()` | Document description from `<meta name="description">` tag |
| `keywords` | `Vec<String>` | `vec![]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `Option<String>` | `Default::default()` | Document author from `<meta name="author">` tag |
| `canonical_url` | `Option<String>` | `Default::default()` | Canonical URL from `<link rel="canonical">` tag |
| `base_href` | `Option<String>` | `Default::default()` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `Option<String>` | `Default::default()` | Document language from `lang` attribute |
| `text_direction` | `Option<TextDirection>` | `Default::default()` | Document text direction from `dir` attribute |
| `open_graph` | `HashMap<String, String>` | `HashMap::new()` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitter_card` | `HashMap<String, String>` | `HashMap::new()` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `meta_tags` | `HashMap<String, String>` | `HashMap::new()` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | --------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `String` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `Option<u32>` | `None` | Index of the parent node (None for root nodes). |
| `children` | `Vec<u32>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `Vec<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `Option<HashMap<String, String>>` | `None` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `None` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| --------------- | ------------------- | ------- | --------------------------------------------------- |
| `nodes` | `Vec<DocumentNode>` | — | All nodes in document reading order. |
| `source_format` | `Option<String>` | `None` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ----------- | -------- | ---------------------- | ---------------------------------------------- |
| `content` | `String` | — | The text content of the cell. |
| `row` | `u32` | — | 0-indexed row position. |
| `col` | `u32` | — | 0-indexed column position. |
| `row_span` | `u32` | `1` | Number of rows this cell spans (default 1). |
| `col_span` | `u32` | `1` | Number of columns this cell spans (default 1). |
| `is_header` | `bool` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------- | ---------------- | ------- | ----------------------------------------- |
| `level` | `u8` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `String` | — | Normalized text content of the header |
| `id` | `Option<String>` | `None` | HTML id attribute if present |
| `depth` | `usize` | — | Document tree depth at the header element |
| `html_offset` | `usize` | — | Byte offset in original HTML document |
##### Methods
[Section titled “Methods”](#methods-1)
###### is_valid()
[Section titled “is_valid()”](#is_valid)
Validate that the header level is within valid range (1-6).
**Returns:**
`true` if level is 1-6, `false` otherwise.
**Signature:**
```rust
pub fn is_valid(&self) -> bool
```
**Example:**
```rust
let valid = HeaderMetadata {
level: 3,
text: "Title".to_string(),
id: None,
depth: 2,
html_offset: 100,
};
assert!(valid.is_valid());
let invalid = HeaderMetadata {
level: 7, // Invalid
text: "Title".to_string(),
id: None,
depth: 2,
html_offset: 100,
};
assert!(!invalid.is_valid());
```
**Returns:** `bool`
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ----------------- | --------------------- | -------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `Vec<HeaderMetadata>` | `vec![]` | Extracted header elements with hierarchy |
| `links` | `Vec<LinkMetadata>` | `vec![]` | Extracted hyperlinks with type classification |
| `images` | `Vec<ImageMetadata>` | `vec![]` | Extracted images with source and dimensions |
| `structured_data` | `Vec<StructuredData>` | `vec![]` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods-2)
###### visit_text()
[Section titled “visit_text()”](#visit_text)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```rust
pub fn visit_text(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_text(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_element_start()
[Section titled “visit_element_start()”](#visit_element_start)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```rust
pub fn visit_element_start(&mut self, ctx: &NodeContext) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_element_start(&todo!());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_element_end()
[Section titled “visit_element_end()”](#visit_element_end)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```rust
pub fn visit_element_end(&mut self, ctx: &NodeContext, output: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_element_end(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `output` | `&str` | Yes | The output |
**Returns:** `VisitResult`
###### visit_link()
[Section titled “visit_link()”](#visit_link)
Visit anchor links `<a href="...">`.
**Signature:**
```rust
pub fn visit_link(&mut self, ctx: &NodeContext, href: &str, text: &str, title: Option<&str>) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_link(&todo!(), "value", "value", Some("value"));
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `href` | `&str` | Yes | The href |
| `text` | `&str` | Yes | The text |
| `title` | `Option<&str>` | No | The title |
**Returns:** `VisitResult`
###### visit_image()
[Section titled “visit_image()”](#visit_image)
Visit images `<img src="...">`.
**Signature:**
```rust
pub fn visit_image(&mut self, ctx: &NodeContext, src: &str, alt: &str, title: Option<&str>) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_image(&todo!(), "value", "value", Some("value"));
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `src` | `&str` | Yes | The src |
| `alt` | `&str` | Yes | The alt |
| `title` | `Option<&str>` | No | The title |
**Returns:** `VisitResult`
###### visit_heading()
[Section titled “visit_heading()”](#visit_heading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```rust
pub fn visit_heading(&mut self, ctx: &NodeContext, level: u32, text: &str, id: Option<&str>) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_heading(&todo!(), 42, "value", Some("value"));
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `level` | `u32` | Yes | The level |
| `text` | `&str` | Yes | The text |
| `id` | `Option<&str>` | No | The id |
**Returns:** `VisitResult`
###### visit_code_block()
[Section titled “visit_code_block()”](#visit_code_block)
Visit code blocks `<pre><code>`.
**Signature:**
```rust
pub fn visit_code_block(&mut self, ctx: &NodeContext, lang: Option<&str>, code: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_code_block(&todo!(), Some("value"), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `lang` | `Option<&str>` | No | The lang |
| `code` | `&str` | Yes | The code |
**Returns:** `VisitResult`
###### visit_code_inline()
[Section titled “visit_code_inline()”](#visit_code_inline)
Visit inline code `<code>`.
**Signature:**
```rust
pub fn visit_code_inline(&mut self, ctx: &NodeContext, code: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_code_inline(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `code` | `&str` | Yes | The code |
**Returns:** `VisitResult`
###### visit_list_item()
[Section titled “visit_list_item()”](#visit_list_item)
Visit list items `<li>`.
**Signature:**
```rust
pub fn visit_list_item(&mut self, ctx: &NodeContext, ordered: bool, marker: &str, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_list_item(&todo!(), true, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
| `marker` | `&str` | Yes | The marker |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_list_start()
[Section titled “visit_list_start()”](#visit_list_start)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```rust
pub fn visit_list_start(&mut self, ctx: &NodeContext, ordered: bool) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_list_start(&todo!(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
**Returns:** `VisitResult`
###### visit_list_end()
[Section titled “visit_list_end()”](#visit_list_end)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```rust
pub fn visit_list_end(&mut self, ctx: &NodeContext, ordered: bool, output: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_list_end(&todo!(), true, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
| `output` | `&str` | Yes | The output |
**Returns:** `VisitResult`
###### visit_table_start()
[Section titled “visit_table_start()”](#visit_table_start)
Called before processing a table `<table>`.
**Signature:**
```rust
pub fn visit_table_start(&mut self, ctx: &NodeContext) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_table_start(&todo!());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_table_row()
[Section titled “visit_table_row()”](#visit_table_row)
Visit table rows `<tr>`.
**Signature:**
```rust
pub fn visit_table_row(&mut self, ctx: &NodeContext, cells: &[String], is_header: bool) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_table_row(&todo!(), &vec![], true);
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `cells` | `&\[String\]` | Yes | The cells |
| `is_header` | `bool` | Yes | The is header |
**Returns:** `VisitResult`
###### visit_table_end()
[Section titled “visit_table_end()”](#visit_table_end)
Called after processing a table `</table>`.
**Signature:**
```rust
pub fn visit_table_end(&mut self, ctx: &NodeContext, output: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_table_end(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `output` | `&str` | Yes | The output |
**Returns:** `VisitResult`
###### visit_blockquote()
[Section titled “visit_blockquote()”](#visit_blockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```rust
pub fn visit_blockquote(&mut self, ctx: &NodeContext, content: &str, depth: usize) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_blockquote(&todo!(), "value", 42);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `content` | `&str` | Yes | The content |
| `depth` | `usize` | Yes | The depth |
**Returns:** `VisitResult`
###### visit_strong()
[Section titled “visit_strong()”](#visit_strong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```rust
pub fn visit_strong(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_strong(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_emphasis()
[Section titled “visit_emphasis()”](#visit_emphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```rust
pub fn visit_emphasis(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_emphasis(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_strikethrough()
[Section titled “visit_strikethrough()”](#visit_strikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```rust
pub fn visit_strikethrough(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_strikethrough(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_underline()
[Section titled “visit_underline()”](#visit_underline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```rust
pub fn visit_underline(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_underline(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_subscript()
[Section titled “visit_subscript()”](#visit_subscript)
Visit subscript elements `<sub>`.
**Signature:**
```rust
pub fn visit_subscript(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_subscript(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_superscript()
[Section titled “visit_superscript()”](#visit_superscript)
Visit superscript elements `<sup>`.
**Signature:**
```rust
pub fn visit_superscript(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_superscript(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_mark()
[Section titled “visit_mark()”](#visit_mark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```rust
pub fn visit_mark(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_mark(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_line_break()
[Section titled “visit_line_break()”](#visit_line_break)
Visit line break elements `<br>`.
**Signature:**
```rust
pub fn visit_line_break(&mut self, ctx: &NodeContext) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_line_break(&todo!());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_horizontal_rule()
[Section titled “visit_horizontal_rule()”](#visit_horizontal_rule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```rust
pub fn visit_horizontal_rule(&mut self, ctx: &NodeContext) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_horizontal_rule(&todo!());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_custom_element()
[Section titled “visit_custom_element()”](#visit_custom_element)
Visit custom elements (web components) or unknown tags.
**Signature:**
```rust
pub fn visit_custom_element(&mut self, ctx: &NodeContext, tag_name: &str, html: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_custom_element(&todo!(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `tag_name` | `&str` | Yes | The tag name |
| `html` | `&str` | Yes | The html |
**Returns:** `VisitResult`
###### visit_definition_list_start()
[Section titled “visit_definition_list_start()”](#visit_definition_list_start)
Visit definition list `<dl>`.
**Signature:**
```rust
pub fn visit_definition_list_start(&mut self, ctx: &NodeContext) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_definition_list_start(&todo!());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_definition_term()
[Section titled “visit_definition_term()”](#visit_definition_term)
Visit definition term `<dt>`.
**Signature:**
```rust
pub fn visit_definition_term(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_definition_term(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_description()
[Section titled “visit_definition_description()”](#visit_definition_description)
Visit definition description `<dd>`.
**Signature:**
```rust
pub fn visit_definition_description(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_definition_description(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_list_end()
[Section titled “visit_definition_list_end()”](#visit_definition_list_end)
Called after processing a definition list `</dl>`.
**Signature:**
```rust
pub fn visit_definition_list_end(&mut self, ctx: &NodeContext, output: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_definition_list_end(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `output` | `&str` | Yes | The output |
**Returns:** `VisitResult`
###### visit_form()
[Section titled “visit_form()”](#visit_form)
Visit form elements `<form>`.
**Signature:**
```rust
pub fn visit_form(&mut self, ctx: &NodeContext, action: Option<&str>, method: Option<&str>) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_form(&todo!(), Some("value"), Some("value"));
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `action` | `Option<&str>` | No | The action |
| `method` | `Option<&str>` | No | The method |
**Returns:** `VisitResult`
###### visit_input()
[Section titled “visit_input()”](#visit_input)
Visit input elements `<input>`.
**Signature:**
```rust
pub fn visit_input(&mut self, ctx: &NodeContext, input_type: &str, name: Option<&str>, value: Option<&str>) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_input(&todo!(), "value", Some("value"), Some("value"));
```
**Parameters:**
| Name | Type | Required | Description |
| ------------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `input_type` | `&str` | Yes | The input type |
| `name` | `Option<&str>` | No | The name |
| `value` | `Option<&str>` | No | The value |
**Returns:** `VisitResult`
###### visit_button()
[Section titled “visit_button()”](#visit_button)
Visit button elements `<button>`.
**Signature:**
```rust
pub fn visit_button(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_button(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_audio()
[Section titled “visit_audio()”](#visit_audio)
Visit audio elements `<audio>`.
**Signature:**
```rust
pub fn visit_audio(&mut self, ctx: &NodeContext, src: Option<&str>) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_audio(&todo!(), Some("value"));
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `src` | `Option<&str>` | No | The src |
**Returns:** `VisitResult`
###### visit_video()
[Section titled “visit_video()”](#visit_video)
Visit video elements `<video>`.
**Signature:**
```rust
pub fn visit_video(&mut self, ctx: &NodeContext, src: Option<&str>) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_video(&todo!(), Some("value"));
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `src` | `Option<&str>` | No | The src |
**Returns:** `VisitResult`
###### visit_iframe()
[Section titled “visit_iframe()”](#visit_iframe)
Visit iframe elements `<iframe>`.
**Signature:**
```rust
pub fn visit_iframe(&mut self, ctx: &NodeContext, src: Option<&str>) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_iframe(&todo!(), Some("value"));
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `src` | `Option<&str>` | No | The src |
**Returns:** `VisitResult`
###### visit_details()
[Section titled “visit_details()”](#visit_details)
Visit details elements `<details>`.
**Signature:**
```rust
pub fn visit_details(&mut self, ctx: &NodeContext, open: bool) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_details(&todo!(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `open` | `bool` | Yes | The open |
**Returns:** `VisitResult`
###### visit_summary()
[Section titled “visit_summary()”](#visit_summary)
Visit summary elements `<summary>`.
**Signature:**
```rust
pub fn visit_summary(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_summary(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_start()
[Section titled “visit_figure_start()”](#visit_figure_start)
Visit figure elements `<figure>`.
**Signature:**
```rust
pub fn visit_figure_start(&mut self, ctx: &NodeContext) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_figure_start(&todo!());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_figcaption()
[Section titled “visit_figcaption()”](#visit_figcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```rust
pub fn visit_figcaption(&mut self, ctx: &NodeContext, text: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_figcaption(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `text` | `&str` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_end()
[Section titled “visit_figure_end()”](#visit_figure_end)
Called after processing a figure `</figure>`.
**Signature:**
```rust
pub fn visit_figure_end(&mut self, ctx: &NodeContext, output: &str) -> VisitResult
```
**Example:**
```rust
let result = instance.visit_figure_end(&todo!(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ---------------- |
| `ctx` | `&NodeContext` | Yes | The node context |
| `output` | `&str` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `Vec<Vec<String>>` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ----- | ------- | ----------------- |
| `width` | `u32` | — | Width in pixels. |
| `height` | `u32` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ------------------------- | ------- | ------------------------------------------------------- |
| `src` | `String` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `Option<String>` | `None` | Alternative text from alt attribute (for accessibility) |
| `title` | `Option<String>` | `None` | Title attribute (often shown as tooltip) |
| `dimensions` | `Option<ImageDimensions>` | `None` | Image dimensions in pixels, if available. |
| `image_type` | `ImageType` | — | Image type classification |
| `attributes` | `HashMap<String, String>` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ------------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `String` | — | The href URL value |
| `text` | `String` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `Option<String>` | `None` | Optional title attribute (often shown as tooltip) |
| `link_type` | `LinkType` | — | Link type classification |
| `rel` | `Vec<String>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `HashMap<String, String>` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent::MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `String` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `String` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext::attributes`, which returns `&BTreeMap<String, String>`. When the context was built with `NodeContext::with_lazy_attributes` (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext::into_owned`.
| Field | Type | Default | Description |
| ----------------- | ---------------- | ------- | ------------------------------------------------------- |
| `node_type` | `NodeType` | — | Coarse-grained node type classification |
| `tag_name` | `String` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `usize` | — | Depth in the DOM tree (0 = root) |
| `index_in_parent` | `usize` | — | Index among siblings (0-based) |
| `parent_tag` | `Option<String>` | `None` | Parent element’s tag name (None if root) |
| `is_inline` | `bool` | — | Whether this element is treated as inline vs block |
##### Methods
[Section titled “Methods”](#methods-3)
###### attributes()
[Section titled “attributes()”](#attributes-1)
Return a reference to the attribute map.
If the context was built with `NodeContext::with_lazy_attributes`, the map is materialized on the first call and cached for subsequent calls. If this method is never called, no allocation occurs for attributes.
**Signature:**
```rust
pub fn attributes(&self) -> HashMap<String, String>
```
**Example:**
```rust
let result = instance.attributes();
```
**Returns:** `HashMap<String, String>`
###### with_owned_attributes()
[Section titled “with_owned_attributes()”](#with_owned_attributes)
Construct a `NodeContext` with an owned attribute map.
Use this when the caller already has materialized attributes.
**Signature:**
```rust
pub fn with_owned_attributes(node_type: NodeType, tag_name: String, attributes: HashMap<String, String>, depth: usize, index_in_parent: usize, parent_tag: Option<String>, is_inline: bool) -> NodeContext
```
**Example:**
```rust
let result = NodeContext::with_owned_attributes(todo!(), "value", std::collections::HashMap::new(), 42, 42, Some("value"), true);
```
**Parameters:**
| Name | Type | Required | Description |
| ----------------- | ------------------------- | -------- | ------------------- |
| `node_type` | `NodeType` | Yes | The node type |
| `tag_name` | `String` | Yes | The tag name |
| `attributes` | `HashMap<String, String>` | Yes | The attributes |
| `depth` | `usize` | Yes | The depth |
| `index_in_parent` | `usize` | Yes | The index in parent |
| `parent_tag` | `Option<String>` | No | The parent tag |
| `is_inline` | `bool` | Yes | The is inline |
**Returns:** `NodeContext`
###### into_owned()
[Section titled “into_owned()”](#into_owned)
Promote any borrowed fields into owned storage so the context can outlive `'a`.
**Signature:**
```rust
pub fn into_owned(self) -> NodeContext
```
**Example:**
```rust
let result = instance.into_owned();
```
**Returns:** `NodeContext`
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------- | --------------------- | ------------------------------- | -------------------------------------------------------------- |
| `enabled` | `bool` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset::Standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `remove_navigation` | `bool` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `remove_forms` | `bool` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
##### Methods
[Section titled “Methods”](#methods-4)
###### default()
[Section titled “default()”](#default-1)
**Signature:**
```rust
pub fn default() -> PreprocessingOptions
```
**Example:**
```rust
let result = PreprocessingOptions::default();
```
**Returns:** `PreprocessingOptions`
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `String` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------- | -------------------- | ------- | --------------------------------------------------------------- |
| `data_type` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `raw_json` | `String` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schema_type` | `Option<String>` | `None` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `String` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `u32` | — | Number of rows. |
| `cols` | `u32` | — | Number of columns. |
| `cells` | `Vec<GridCell>` | `vec![]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this vec is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty vec. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode::content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `u32` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `u32` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------- | ---------------------------------------------------- |
| `LeftToRight` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Anchor` | Anchor link within same document (href starts with #) |
| `Internal` | Internal link within same domain |
| `External` | External link to different domain |
| `Email` | Email link (mailto:) |
| `Phone` | Phone link (tel:) |
| `Other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ----------- | -------------------------------------------------- |
| `DataUri` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | Inline SVG element |
| `External` | External image URL (http/https) |
| `Relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JsonLd` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `Rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | Always use the Tier-2 (`tl::parse` + walk) path, skipping Tier-1. |
| `Tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | A heading element (h1-h6). — Fields: `level`: `u8`, `text`: `String` |
| `Paragraph` | A paragraph of text. — Fields: `text`: `String` |
| `List` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `bool` |
| `ListItem` | A single list item. — Fields: `text`: `String` |
| `Table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `Image` | An image element. — Fields: `description`: `String`, `src`: `String`, `image_index`: `u32` |
| `Code` | A code block or inline code. — Fields: `text`: `String`, `language`: `String` |
| `Quote` | A block quote container. |
| `DefinitionList` | A definition list container. |
| `DefinitionItem` | A definition list entry with term and description. — Fields: `term`: `String`, `definition`: `String` |
| `RawBlock` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `String`, `content`: `String` |
| `MetadataBlock` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `Vec<MetadataEntry>` |
| `Group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `String`, `heading_level`: `u8`, `heading_text`: `String` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | Bold / strong emphasis. |
| `Italic` | Italic / emphasis. |
| `Underline` | Underline. |
| `Strikethrough` | Strikethrough / deleted text. |
| `Code` | Inline code. |
| `Subscript` | Subscript text. |
| `Superscript` | Superscript text. |
| `Highlight` | Highlighted / marked text. |
| `Link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `String`, `title`: `String` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | The input was truncated due to size limits. |
| `MalformedHtml` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ----------------------- | ---------------------------------------------- |
| `Text` | Text node (most frequent - 100+ per document) |
| `Element` | Generic element node |
| `Heading` | Heading elements (h1-h6) |
| `Paragraph` | Paragraph element |
| `Div` | Generic div container |
| `Blockquote` | Blockquote element |
| `Pre` | Preformatted text block |
| `Hr` | Horizontal rule |
| `List` | Ordered or unordered list (ul, ol) |
| `ListItem` | List item (li) |
| `DefinitionList` | Definition list (dl) |
| `DefinitionTerm` | Definition term (dt) |
| `DefinitionDescription` | Definition description (dd) |
| `Table` | Table element |
| `TableRow` | Table row (tr) |
| `TableCell` | Table cell (td, th) |
| `TableHeader` | Table header cell (th) |
| `TableBody` | Table body (tbody) |
| `TableHead` | Table head (thead) |
| `TableFoot` | Table foot (tfoot) |
| `Link` | Anchor link (a) |
| `Image` | Image (img) |
| `Strong` | Strong/bold (strong, b) |
| `Em` | Emphasis/italic (em, i) |
| `Code` | Inline code (code) |
| `Strikethrough` | Strikethrough (s, del, strike) |
| `Underline` | Underline (u, ins) |
| `Subscript` | Subscript (sub) |
| `Superscript` | Superscript (sup) |
| `Mark` | Mark/highlight (mark) |
| `Small` | Small text (small) |
| `Br` | Line break (br) |
| `Span` | Span element |
| `Article` | Article element |
| `Section` | Section element |
| `Nav` | Navigation element |
| `Aside` | Aside element |
| `Header` | Header element |
| `Footer` | Footer element |
| `Main` | Main element |
| `Figure` | Figure element |
| `Figcaption` | Figure caption |
| `Time` | Time element |
| `Details` | Details element |
| `Summary` | Summary element |
| `Form` | Form element |
| `Input` | Input element |
| `Select` | Select element |
| `Option` | Option element |
| `Button` | Button element |
| `Textarea` | Textarea element |
| `Label` | Label element |
| `Fieldset` | Fieldset element |
| `Legend` | Legend element |
| `Audio` | Audio element |
| `Video` | Video element |
| `Picture` | Picture element |
| `Source` | Source element |
| `Iframe` | Iframe element |
| `Svg` | SVG element |
| `Canvas` | Canvas element |
| `Ruby` | Ruby annotation |
| `Rt` | Ruby text |
| `Rp` | Ruby parenthesis |
| `Abbr` | Abbreviation |
| `Kbd` | Keyboard input |
| `Samp` | Sample output |
| `Var` | Variable |
| `Cite` | Citation |
| `Q` | Quote |
| `Del` | Deleted text |
| `Ins` | Inserted text |
| `Data` | Data element |
| `Meter` | Meter element |
| `Progress` | Progress element |
| `Output` | Output element |
| `Template` | Template element |
| `Slot` | Slot element |
| `Html` | HTML root element |
| `Head` | Head element |
| `Body` | Body element |
| `Title` | Title element |
| `Meta` | Meta element |
| `LinkTag` | Link element (not anchor) |
| `Style` | Style element |
| `Script` | Script element |
| `Base` | Base element |
| `Custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Continue` | Continue with default conversion behavior |
| `Custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `String` |
| `Skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PreserveHtml` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `Error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `String` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseError` | HTML parsing error |
| `SanitizationError` | HTML sanitization error |
| `ConfigError` | Invalid configuration |
| `IoError` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError::from(io_error)` to convert from `std::io::Error`. |
| `Panic` | Internal error caught during conversion |
| `InvalidInput` | Invalid input data |
| `InputTooLarge` | Input exceeds the configured byte limit. |
| `Other` | Generic conversion error |
***
# Swift API Reference
## Swift API Reference v3.17.2
[Section titled “Swift API Reference v3.17.2”](#swift-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```swift
public static func convert(html: String, options: ConversionOptions? = nil) throws -> ConversionResult
```
**Example:**
```swift
let result = try convert("value", ConversionOptions())
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------------- | -------- | ------------------ |
| `html` | `String` | Yes | The html |
| `options` | `ConversionOptions?` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Throws `ConversionError`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ---------------------------- | ---------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `headingStyle` | `HeadingStyle` | `HeadingStyle.atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `listIndentType` | `ListIndentType` | `ListIndentType.spaces` | How to indent nested list items (spaces or tab). |
| `listIndentWidth` | `UInt` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `String` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strongEmSymbol` | `String` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escapeAsterisks` | `Bool` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escapeUnderscores` | `Bool` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escapeMisc` | `Bool` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escapeAscii` | `Bool` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `codeLanguage` | `String` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `Bool` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expandAbbreviations` | `Bool` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `includeBlockquoteCitations` | `Bool` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `defaultTitle` | `Bool` | `false` | Emit a default title when no `<title>` tag is present. |
| `brInTables` | `Bool` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compactTables` | `Bool` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlightStyle` | `HighlightStyle` | `HighlightStyle.doubleEqual` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extractMetadata` | `Bool` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespaceMode` | `WhitespaceMode` | `WhitespaceMode.normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `stripNewlines` | `Bool` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `Bool` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrapWidth` | `UInt` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convertAsInline` | `Bool` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `subSymbol` | `String` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `supSymbol` | `String` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newlineStyle` | `NewlineStyle` | `NewlineStyle.spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `codeBlockStyle` | `CodeBlockStyle` | `CodeBlockStyle.backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keepInlineImagesIn` | `\[String\]` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `String` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `Bool` | `false` | Emit debug information during conversion. |
| `stripTags` | `\[String\]` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserveTags` | `\[String\]` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skipImages` | `Bool` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inlineDataMedia` | `InlineDataMedia` | `InlineDataMedia.keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hiddenContent` | `HiddenContent` | `HiddenContent.drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `urlEscapeStyle` | `UrlEscapeStyle` | `UrlEscapeStyle.angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `linkStyle` | `LinkStyle` | `LinkStyle.inline` | Link rendering style (inline or reference). |
| `outputFormat` | `OutputFormat` | `OutputFormat.markdown` | Target output format (Markdown, plain text, etc.). |
| `includeDocumentStructure` | `Bool` | `false` | Include structured document tree in result. |
| `extractImages` | `Bool` | `false` | Extract inline images from data URIs and SVGs. |
| `maxImageSize` | `UInt64` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `maxInputSize` | `UInt64?` | `null` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `null`. Set `Some(bytes)` to choose another limit or `null` to disable it. |
| `captureSvg` | `Bool` | `false` | Capture SVG elements as images. |
| `inferDimensions` | `Bool` | `true` | Infer image dimensions from data. |
| `maxDepth` | `UInt?` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `excludeSelectors` | `\[String\]` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tierStrategy` | `TierStrategy` | `TierStrategy.auto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `baseUrl` | `String?` | `null` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `null` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle?` | `null` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `String?` | `null` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure?` | `null` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `null` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `\[TableData\]` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `\[ProcessingWarning\]` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| --------------- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `String?` | `null` | Document title from `<title>` tag |
| `description` | `String?` | `null` | Document description from `<meta name="description">` tag |
| `keywords` | `\[String\]` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `String?` | `null` | Document author from `<meta name="author">` tag |
| `canonicalUrl` | `String?` | `null` | Canonical URL from `<link rel="canonical">` tag |
| `baseHref` | `String?` | `null` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `String?` | `null` | Document language from `lang` attribute |
| `textDirection` | `TextDirection?` | `null` | Document text direction from `dir` attribute |
| `openGraph` | `\[String: String\]` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitterCard` | `\[String: String\]` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `metaTags` | `\[String: String\]` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | --------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `String` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `UInt32?` | `null` | Index of the parent node (None for root nodes). |
| `children` | `\[UInt32\]` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `\[TextAnnotation\]` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `\[String: String\]?` | `null` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `null` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| -------------- | ------------------ | ------- | --------------------------------------------------- |
| `nodes` | `\[DocumentNode\]` | — | All nodes in document reading order. |
| `sourceFormat` | `String?` | `null` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ---------- | -------- | ---------------------- | ---------------------------------------------- |
| `content` | `String` | — | The text content of the cell. |
| `row` | `UInt32` | — | 0-indexed row position. |
| `col` | `UInt32` | — | 0-indexed column position. |
| `rowSpan` | `UInt32` | `1` | Number of rows this cell spans (default 1). |
| `colSpan` | `UInt32` | `1` | Number of columns this cell spans (default 1). |
| `isHeader` | `Bool` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------ | --------- | ------- | ----------------------------------------- |
| `level` | `UInt8` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `String` | — | Normalized text content of the header |
| `id` | `String?` | `null` | HTML id attribute if present |
| `depth` | `UInt` | — | Document tree depth at the header element |
| `htmlOffset` | `UInt` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ---------------- | -------------------- | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `\[HeaderMetadata\]` | `[]` | Extracted header elements with hierarchy |
| `links` | `\[LinkMetadata\]` | `[]` | Extracted hyperlinks with type classification |
| `images` | `\[ImageMetadata\]` | `[]` | Extracted images with source and dimensions |
| `structuredData` | `\[StructuredData\]` | `[]` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### visitText()
[Section titled “visitText()”](#visittext)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```swift
public func visitText(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitText(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitElementStart()
[Section titled “visitElementStart()”](#visitelementstart)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```swift
public func visitElementStart(ctx: NodeContext) -> VisitResult
```
**Example:**
```swift
let result = instance.visitElementStart(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitElementEnd()
[Section titled “visitElementEnd()”](#visitelementend)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```swift
public func visitElementEnd(ctx: NodeContext, output: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitElementEnd(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitLink()
[Section titled “visitLink()”](#visitlink)
Visit anchor links `<a href="...">`.
**Signature:**
```swift
public func visitLink(ctx: NodeContext, href: String, text: String, title: String? = nil) -> VisitResult
```
**Example:**
```swift
let result = instance.visitLink(NodeContext(), "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `href` | `String` | Yes | The href |
| `text` | `String` | Yes | The text |
| `title` | `String?` | No | The title |
**Returns:** `VisitResult`
###### visitImage()
[Section titled “visitImage()”](#visitimage)
Visit images `<img src="...">`.
**Signature:**
```swift
public func visitImage(ctx: NodeContext, src: String, alt: String, title: String? = nil) -> VisitResult
```
**Example:**
```swift
let result = instance.visitImage(NodeContext(), "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String` | Yes | The src |
| `alt` | `String` | Yes | The alt |
| `title` | `String?` | No | The title |
**Returns:** `VisitResult`
###### visitHeading()
[Section titled “visitHeading()”](#visitheading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```swift
public func visitHeading(ctx: NodeContext, level: UInt32, text: String, id: String? = nil) -> VisitResult
```
**Example:**
```swift
let result = instance.visitHeading(NodeContext(), 42, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `level` | `UInt32` | Yes | The level |
| `text` | `String` | Yes | The text |
| `id` | `String?` | No | The id |
**Returns:** `VisitResult`
###### visitCodeBlock()
[Section titled “visitCodeBlock()”](#visitcodeblock)
Visit code blocks `<pre><code>`.
**Signature:**
```swift
public func visitCodeBlock(ctx: NodeContext, lang: String? = nil, code: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitCodeBlock(NodeContext(), "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `lang` | `String?` | No | The lang |
| `code` | `String` | Yes | The code |
**Returns:** `VisitResult`
###### visitCodeInline()
[Section titled “visitCodeInline()”](#visitcodeinline)
Visit inline code `<code>`.
**Signature:**
```swift
public func visitCodeInline(ctx: NodeContext, code: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitCodeInline(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `code` | `String` | Yes | The code |
**Returns:** `VisitResult`
###### visitListItem()
[Section titled “visitListItem()”](#visitlistitem)
Visit list items `<li>`.
**Signature:**
```swift
public func visitListItem(ctx: NodeContext, ordered: Bool, marker: String, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitListItem(NodeContext(), true, "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `Bool` | Yes | The ordered |
| `marker` | `String` | Yes | The marker |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitListStart()
[Section titled “visitListStart()”](#visitliststart)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```swift
public func visitListStart(ctx: NodeContext, ordered: Bool) -> VisitResult
```
**Example:**
```swift
let result = instance.visitListStart(NodeContext(), true)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `Bool` | Yes | The ordered |
**Returns:** `VisitResult`
###### visitListEnd()
[Section titled “visitListEnd()”](#visitlistend)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```swift
public func visitListEnd(ctx: NodeContext, ordered: Bool, output: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitListEnd(NodeContext(), true, "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `Bool` | Yes | The ordered |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitTableStart()
[Section titled “visitTableStart()”](#visittablestart)
Called before processing a table `<table>`.
**Signature:**
```swift
public func visitTableStart(ctx: NodeContext) -> VisitResult
```
**Example:**
```swift
let result = instance.visitTableStart(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitTableRow()
[Section titled “visitTableRow()”](#visittablerow)
Visit table rows `<tr>`.
**Signature:**
```swift
public func visitTableRow(ctx: NodeContext, cells: [String], isHeader: Bool) -> VisitResult
```
**Example:**
```swift
let result = instance.visitTableRow(NodeContext(), [], true)
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `cells` | `\[String\]` | Yes | The cells |
| `isHeader` | `Bool` | Yes | The is header |
**Returns:** `VisitResult`
###### visitTableEnd()
[Section titled “visitTableEnd()”](#visittableend)
Called after processing a table `</table>`.
**Signature:**
```swift
public func visitTableEnd(ctx: NodeContext, output: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitTableEnd(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitBlockquote()
[Section titled “visitBlockquote()”](#visitblockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```swift
public func visitBlockquote(ctx: NodeContext, content: String, depth: UInt) -> VisitResult
```
**Example:**
```swift
let result = instance.visitBlockquote(NodeContext(), "value", 42)
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `content` | `String` | Yes | The content |
| `depth` | `UInt` | Yes | The depth |
**Returns:** `VisitResult`
###### visitStrong()
[Section titled “visitStrong()”](#visitstrong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```swift
public func visitStrong(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitStrong(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitEmphasis()
[Section titled “visitEmphasis()”](#visitemphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```swift
public func visitEmphasis(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitEmphasis(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitStrikethrough()
[Section titled “visitStrikethrough()”](#visitstrikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```swift
public func visitStrikethrough(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitStrikethrough(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitUnderline()
[Section titled “visitUnderline()”](#visitunderline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```swift
public func visitUnderline(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitUnderline(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitSubscript()
[Section titled “visitSubscript()”](#visitsubscript)
Visit subscript elements `<sub>`.
**Signature:**
```swift
public func visitSubscript(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitSubscript(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitSuperscript()
[Section titled “visitSuperscript()”](#visitsuperscript)
Visit superscript elements `<sup>`.
**Signature:**
```swift
public func visitSuperscript(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitSuperscript(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitMark()
[Section titled “visitMark()”](#visitmark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```swift
public func visitMark(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitMark(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitLineBreak()
[Section titled “visitLineBreak()”](#visitlinebreak)
Visit line break elements `<br>`.
**Signature:**
```swift
public func visitLineBreak(ctx: NodeContext) -> VisitResult
```
**Example:**
```swift
let result = instance.visitLineBreak(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitHorizontalRule()
[Section titled “visitHorizontalRule()”](#visithorizontalrule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```swift
public func visitHorizontalRule(ctx: NodeContext) -> VisitResult
```
**Example:**
```swift
let result = instance.visitHorizontalRule(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitCustomElement()
[Section titled “visitCustomElement()”](#visitcustomelement)
Visit custom elements (web components) or unknown tags.
**Signature:**
```swift
public func visitCustomElement(ctx: NodeContext, tagName: String, html: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitCustomElement(NodeContext(), "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `tagName` | `String` | Yes | The tag name |
| `html` | `String` | Yes | The html |
**Returns:** `VisitResult`
###### visitDefinitionListStart()
[Section titled “visitDefinitionListStart()”](#visitdefinitionliststart)
Visit definition list `<dl>`.
**Signature:**
```swift
public func visitDefinitionListStart(ctx: NodeContext) -> VisitResult
```
**Example:**
```swift
let result = instance.visitDefinitionListStart(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitDefinitionTerm()
[Section titled “visitDefinitionTerm()”](#visitdefinitionterm)
Visit definition term `<dt>`.
**Signature:**
```swift
public func visitDefinitionTerm(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitDefinitionTerm(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionDescription()
[Section titled “visitDefinitionDescription()”](#visitdefinitiondescription)
Visit definition description `<dd>`.
**Signature:**
```swift
public func visitDefinitionDescription(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitDefinitionDescription(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionListEnd()
[Section titled “visitDefinitionListEnd()”](#visitdefinitionlistend)
Called after processing a definition list `</dl>`.
**Signature:**
```swift
public func visitDefinitionListEnd(ctx: NodeContext, output: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitDefinitionListEnd(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
###### visitForm()
[Section titled “visitForm()”](#visitform)
Visit form elements `<form>`.
**Signature:**
```swift
public func visitForm(ctx: NodeContext, action: String? = nil, method: String? = nil) -> VisitResult
```
**Example:**
```swift
let result = instance.visitForm(NodeContext(), "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `action` | `String?` | No | The action |
| `method` | `String?` | No | The method |
**Returns:** `VisitResult`
###### visitInput()
[Section titled “visitInput()”](#visitinput)
Visit input elements `<input>`.
**Signature:**
```swift
public func visitInput(ctx: NodeContext, inputType: String, name: String? = nil, value: String? = nil) -> VisitResult
```
**Example:**
```swift
let result = instance.visitInput(NodeContext(), "value", "value", "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `inputType` | `String` | Yes | The input type |
| `name` | `String?` | No | The name |
| `value` | `String?` | No | The value |
**Returns:** `VisitResult`
###### visitButton()
[Section titled “visitButton()”](#visitbutton)
Visit button elements `<button>`.
**Signature:**
```swift
public func visitButton(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitButton(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitAudio()
[Section titled “visitAudio()”](#visitaudio)
Visit audio elements `<audio>`.
**Signature:**
```swift
public func visitAudio(ctx: NodeContext, src: String? = nil) -> VisitResult
```
**Example:**
```swift
let result = instance.visitAudio(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String?` | No | The src |
**Returns:** `VisitResult`
###### visitVideo()
[Section titled “visitVideo()”](#visitvideo)
Visit video elements `<video>`.
**Signature:**
```swift
public func visitVideo(ctx: NodeContext, src: String? = nil) -> VisitResult
```
**Example:**
```swift
let result = instance.visitVideo(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String?` | No | The src |
**Returns:** `VisitResult`
###### visitIframe()
[Section titled “visitIframe()”](#visitiframe)
Visit iframe elements `<iframe>`.
**Signature:**
```swift
public func visitIframe(ctx: NodeContext, src: String? = nil) -> VisitResult
```
**Example:**
```swift
let result = instance.visitIframe(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `String?` | No | The src |
**Returns:** `VisitResult`
###### visitDetails()
[Section titled “visitDetails()”](#visitdetails)
Visit details elements `<details>`.
**Signature:**
```swift
public func visitDetails(ctx: NodeContext, open: Bool) -> VisitResult
```
**Example:**
```swift
let result = instance.visitDetails(NodeContext(), true)
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `open` | `Bool` | Yes | The open |
**Returns:** `VisitResult`
###### visitSummary()
[Section titled “visitSummary()”](#visitsummary)
Visit summary elements `<summary>`.
**Signature:**
```swift
public func visitSummary(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitSummary(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureStart()
[Section titled “visitFigureStart()”](#visitfigurestart)
Visit figure elements `<figure>`.
**Signature:**
```swift
public func visitFigureStart(ctx: NodeContext) -> VisitResult
```
**Example:**
```swift
let result = instance.visitFigureStart(NodeContext())
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitFigcaption()
[Section titled “visitFigcaption()”](#visitfigcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```swift
public func visitFigcaption(ctx: NodeContext, text: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitFigcaption(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `String` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureEnd()
[Section titled “visitFigureEnd()”](#visitfigureend)
Called after processing a figure `</figure>`.
**Signature:**
```swift
public func visitFigureEnd(ctx: NodeContext, output: String) -> VisitResult
```
**Example:**
```swift
let result = instance.visitFigureEnd(NodeContext(), "value")
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `String` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `[[String]]` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | -------- | ------- | ----------------- |
| `width` | `UInt32` | — | Width in pixels. |
| `height` | `UInt32` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | ------------------------------------------------------- |
| `src` | `String` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `String?` | `null` | Alternative text from alt attribute (for accessibility) |
| `title` | `String?` | `null` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions?` | `null` | Image dimensions in pixels, if available. |
| `imageType` | `ImageType` | — | Image type classification |
| `attributes` | `\[String: String\]` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `String` | — | The href URL value |
| `text` | `String` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `String?` | `null` | Optional title attribute (often shown as tooltip) |
| `linkType` | `LinkType` | — | Link type classification |
| `rel` | `\[String\]` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `\[String: String\]` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `String` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `String` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `[String: String]`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| --------------- | ---------- | ------- | ------------------------------------------------------- |
| `nodeType` | `NodeType` | — | Coarse-grained node type classification |
| `tagName` | `String` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `UInt` | — | Depth in the DOM tree (0 = root) |
| `indexInParent` | `UInt` | — | Index among siblings (0-based) |
| `parentTag` | `String?` | `null` | Parent element’s tag name (None if root) |
| `isInline` | `Bool` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------ | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `enabled` | `Bool` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset.standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `removeNavigation` | `Bool` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `removeForms` | `Bool` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `String` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | --------------------------------------------------------------- |
| `dataType` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `rawJson` | `String` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schemaType` | `String?` | `null` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `String` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `UInt32` | — | Number of rows. |
| `cols` | `UInt32` | — | Number of columns. |
| `cells` | `\[GridCell\]` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `UInt32` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `UInt32` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------- | ---------------------------------------------------- |
| `LeftToRight` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Anchor` | Anchor link within same document (href starts with #) |
| `Internal` | Internal link within same domain |
| `External` | External link to different domain |
| `Email` | Email link (mailto:) |
| `Phone` | Phone link (tel:) |
| `Other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ----------- | -------------------------------------------------- |
| `DataUri` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | Inline SVG element |
| `External` | External image URL (http/https) |
| `Relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JsonLd` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `Rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `Tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | A heading element (h1-h6). — Fields: `level`: `UInt8`, `text`: `String` |
| `Paragraph` | A paragraph of text. — Fields: `text`: `String` |
| `List` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `Bool` |
| `ListItem` | A single list item. — Fields: `text`: `String` |
| `Table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `Image` | An image element. — Fields: `description`: `String`, `src`: `String`, `imageIndex`: `UInt32` |
| `Code` | A code block or inline code. — Fields: `text`: `String`, `language`: `String` |
| `Quote` | A block quote container. |
| `DefinitionList` | A definition list container. |
| `DefinitionItem` | A definition list entry with term and description. — Fields: `term`: `String`, `definition`: `String` |
| `RawBlock` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `String`, `content`: `String` |
| `MetadataBlock` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `[MetadataEntry]` |
| `Group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `String`, `headingLevel`: `UInt8`, `headingText`: `String` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | Bold / strong emphasis. |
| `Italic` | Italic / emphasis. |
| `Underline` | Underline. |
| `Strikethrough` | Strikethrough / deleted text. |
| `Code` | Inline code. |
| `Subscript` | Subscript text. |
| `Superscript` | Superscript text. |
| `Highlight` | Highlighted / marked text. |
| `Link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `String`, `title`: `String` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | The input was truncated due to size limits. |
| `MalformedHtml` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ----------------------- | ---------------------------------------------- |
| `Text` | Text node (most frequent - 100+ per document) |
| `Element` | Generic element node |
| `Heading` | Heading elements (h1-h6) |
| `Paragraph` | Paragraph element |
| `Div` | Generic div container |
| `Blockquote` | Blockquote element |
| `Pre` | Preformatted text block |
| `Hr` | Horizontal rule |
| `List` | Ordered or unordered list (ul, ol) |
| `ListItem` | List item (li) |
| `DefinitionList` | Definition list (dl) |
| `DefinitionTerm` | Definition term (dt) |
| `DefinitionDescription` | Definition description (dd) |
| `Table` | Table element |
| `TableRow` | Table row (tr) |
| `TableCell` | Table cell (td, th) |
| `TableHeader` | Table header cell (th) |
| `TableBody` | Table body (tbody) |
| `TableHead` | Table head (thead) |
| `TableFoot` | Table foot (tfoot) |
| `Link` | Anchor link (a) |
| `Image` | Image (img) |
| `Strong` | Strong/bold (strong, b) |
| `Em` | Emphasis/italic (em, i) |
| `Code` | Inline code (code) |
| `Strikethrough` | Strikethrough (s, del, strike) |
| `Underline` | Underline (u, ins) |
| `Subscript` | Subscript (sub) |
| `Superscript` | Superscript (sup) |
| `Mark` | Mark/highlight (mark) |
| `Small` | Small text (small) |
| `Br` | Line break (br) |
| `Span` | Span element |
| `Article` | Article element |
| `Section` | Section element |
| `Nav` | Navigation element |
| `Aside` | Aside element |
| `Header` | Header element |
| `Footer` | Footer element |
| `Main` | Main element |
| `Figure` | Figure element |
| `Figcaption` | Figure caption |
| `Time` | Time element |
| `Details` | Details element |
| `Summary` | Summary element |
| `Form` | Form element |
| `Input` | Input element |
| `Select` | Select element |
| `Option` | Option element |
| `Button` | Button element |
| `Textarea` | Textarea element |
| `Label` | Label element |
| `Fieldset` | Fieldset element |
| `Legend` | Legend element |
| `Audio` | Audio element |
| `Video` | Video element |
| `Picture` | Picture element |
| `Source` | Source element |
| `Iframe` | Iframe element |
| `Svg` | SVG element |
| `Canvas` | Canvas element |
| `Ruby` | Ruby annotation |
| `Rt` | Ruby text |
| `Rp` | Ruby parenthesis |
| `Abbr` | Abbreviation |
| `Kbd` | Keyboard input |
| `Samp` | Sample output |
| `Var` | Variable |
| `Cite` | Citation |
| `Q` | Quote |
| `Del` | Deleted text |
| `Ins` | Inserted text |
| `Data` | Data element |
| `Meter` | Meter element |
| `Progress` | Progress element |
| `Output` | Output element |
| `Template` | Template element |
| `Slot` | Slot element |
| `Html` | HTML root element |
| `Head` | Head element |
| `Body` | Body element |
| `Title` | Title element |
| `Meta` | Meta element |
| `LinkTag` | Link element (not anchor) |
| `Style` | Style element |
| `Script` | Script element |
| `Base` | Base element |
| `Custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Continue` | Continue with default conversion behavior |
| `Custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `String` |
| `Skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PreserveHtml` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `Error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `String` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parseError` | HTML parsing error |
| `sanitizationError` | HTML sanitization error |
| `configError` | Invalid configuration |
| `ioError` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `panic` | Internal error caught during conversion |
| `invalidInput` | Invalid input data |
| `inputTooLarge` | Input exceeds the configured byte limit. |
| `other` | Generic conversion error |
***
# TypeScript API Reference
## TypeScript API Reference v3.17.2
[Section titled “TypeScript API Reference v3.17.2”](#typescript-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```typescript
function convert(html: string, options?: ConversionOptions): ConversionResult
```
**Example:**
```typescript
const result = convert("value", new ConversionOptions());
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------------------- | -------- | ------------------ |
| `html` | `string` | Yes | The html |
| `options` | `ConversionOptions \| null` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Throws `Error` with a descriptive message.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ---------------------------- | ----------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `headingStyle` | `HeadingStyle` | `HeadingStyle.Atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `listIndentType` | `ListIndentType` | `ListIndentType.Spaces` | How to indent nested list items (spaces or tab). |
| `listIndentWidth` | `number` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `string` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strongEmSymbol` | `string` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escapeAsterisks` | `boolean` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escapeUnderscores` | `boolean` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escapeMisc` | `boolean` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escapeAscii` | `boolean` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `codeLanguage` | `string` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `boolean` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expandAbbreviations` | `boolean` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `includeBlockquoteCitations` | `boolean` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `defaultTitle` | `boolean` | `false` | Emit a default title when no `<title>` tag is present. |
| `brInTables` | `boolean` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compactTables` | `boolean` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlightStyle` | `HighlightStyle` | `HighlightStyle.DoubleEqual` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extractMetadata` | `boolean` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespaceMode` | `WhitespaceMode` | `WhitespaceMode.Normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `stripNewlines` | `boolean` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `boolean` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrapWidth` | `number` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convertAsInline` | `boolean` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `subSymbol` | `string` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `supSymbol` | `string` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newlineStyle` | `NewlineStyle` | `NewlineStyle.Spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `codeBlockStyle` | `CodeBlockStyle` | `CodeBlockStyle.Backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keepInlineImagesIn` | `Array<string>` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `string` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `boolean` | `false` | Emit debug information during conversion. |
| `stripTags` | `Array<string>` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserveTags` | `Array<string>` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skipImages` | `boolean` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inlineDataMedia` | `InlineDataMedia` | `InlineDataMedia.Keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hiddenContent` | `HiddenContent` | `HiddenContent.Drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `urlEscapeStyle` | `UrlEscapeStyle` | `UrlEscapeStyle.Angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `linkStyle` | `LinkStyle` | `LinkStyle.Inline` | Link rendering style (inline or reference). |
| `outputFormat` | `OutputFormat` | `OutputFormat.Markdown` | Target output format (Markdown, plain text, etc.). |
| `includeDocumentStructure` | `boolean` | `false` | Include structured document tree in result. |
| `extractImages` | `boolean` | `false` | Extract inline images from data URIs and SVGs. |
| `maxImageSize` | `number` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `maxInputSize` | `number \| null` | `null` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `null`. Set `Some(bytes)` to choose another limit or `null` to disable it. |
| `captureSvg` | `boolean` | `false` | Capture SVG elements as images. |
| `inferDimensions` | `boolean` | `true` | Infer image dimensions from data. |
| `maxDepth` | `number \| null` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `excludeSelectors` | `Array<string>` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tierStrategy` | `TierStrategy` | `TierStrategy.Auto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `baseUrl` | `string \| null` | `null` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `null` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle \| null` | `null` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `string \| null` | `null` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure \| null` | `null` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `null` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `Array<TableData>` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `Array<ProcessingWarning>` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| --------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `string \| null` | `null` | Document title from `<title>` tag |
| `description` | `string \| null` | `null` | Document description from `<meta name="description">` tag |
| `keywords` | `Array<string>` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `string \| null` | `null` | Document author from `<meta name="author">` tag |
| `canonicalUrl` | `string \| null` | `null` | Canonical URL from `<link rel="canonical">` tag |
| `baseHref` | `string \| null` | `null` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `string \| null` | `null` | Document language from `lang` attribute |
| `textDirection` | `TextDirection \| null` | `null` | Document text direction from `dir` attribute |
| `openGraph` | `Record<string, string>` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitterCard` | `Record<string, string>` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `metaTags` | `Record<string, string>` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | -------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `number \| null` | `null` | Index of the parent node (None for root nodes). |
| `children` | `Array<number>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `Array<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `Record<string, string> \| null` | `null` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `null` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| -------------- | --------------------- | ------- | --------------------------------------------------- |
| `nodes` | `Array<DocumentNode>` | — | All nodes in document reading order. |
| `sourceFormat` | `string \| null` | `null` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ---------- | --------- | ---------------------- | ---------------------------------------------- |
| `content` | `string` | — | The text content of the cell. |
| `row` | `number` | — | 0-indexed row position. |
| `col` | `number` | — | 0-indexed column position. |
| `rowSpan` | `number` | `1` | Number of rows this cell spans (default 1). |
| `colSpan` | `number` | `1` | Number of columns this cell spans (default 1). |
| `isHeader` | `boolean` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------ | ---------------- | ------- | ----------------------------------------- |
| `level` | `number` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `string` | — | Normalized text content of the header |
| `id` | `string \| null` | `null` | HTML id attribute if present |
| `depth` | `number` | — | Document tree depth at the header element |
| `htmlOffset` | `number` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ---------------- | ----------------------- | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `Array<HeaderMetadata>` | `[]` | Extracted header elements with hierarchy |
| `links` | `Array<LinkMetadata>` | `[]` | Extracted hyperlinks with type classification |
| `images` | `Array<ImageMetadata>` | `[]` | Extracted images with source and dimensions |
| `structuredData` | `Array<StructuredData>` | `[]` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### visitText()
[Section titled “visitText()”](#visittext)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```typescript
visitText(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitText(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitElementStart()
[Section titled “visitElementStart()”](#visitelementstart)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```typescript
visitElementStart(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitElementStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitElementEnd()
[Section titled “visitElementEnd()”](#visitelementend)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```typescript
visitElementEnd(ctx: NodeContext, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitElementEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### visitLink()
[Section titled “visitLink()”](#visitlink)
Visit anchor links `<a href="...">`.
**Signature:**
```typescript
visitLink(ctx: NodeContext, href: string, text: string, title: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitLink(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `href` | `string` | Yes | The href |
| `text` | `string` | Yes | The text |
| `title` | `string \| null` | No | The title |
**Returns:** `VisitResult`
###### visitImage()
[Section titled “visitImage()”](#visitimage)
Visit images `<img src="...">`.
**Signature:**
```typescript
visitImage(ctx: NodeContext, src: string, alt: string, title: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitImage(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `string` | Yes | The src |
| `alt` | `string` | Yes | The alt |
| `title` | `string \| null` | No | The title |
**Returns:** `VisitResult`
###### visitHeading()
[Section titled “visitHeading()”](#visitheading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```typescript
visitHeading(ctx: NodeContext, level: number, text: string, id: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitHeading(new NodeContext(), 42, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `level` | `number` | Yes | The level |
| `text` | `string` | Yes | The text |
| `id` | `string \| null` | No | The id |
**Returns:** `VisitResult`
###### visitCodeBlock()
[Section titled “visitCodeBlock()”](#visitcodeblock)
Visit code blocks `<pre><code>`.
**Signature:**
```typescript
visitCodeBlock(ctx: NodeContext, lang: string, code: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitCodeBlock(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `lang` | `string \| null` | No | The lang |
| `code` | `string` | Yes | The code |
**Returns:** `VisitResult`
###### visitCodeInline()
[Section titled “visitCodeInline()”](#visitcodeinline)
Visit inline code `<code>`.
**Signature:**
```typescript
visitCodeInline(ctx: NodeContext, code: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitCodeInline(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `code` | `string` | Yes | The code |
**Returns:** `VisitResult`
###### visitListItem()
[Section titled “visitListItem()”](#visitlistitem)
Visit list items `<li>`.
**Signature:**
```typescript
visitListItem(ctx: NodeContext, ordered: boolean, marker: string, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitListItem(new NodeContext(), true, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean` | Yes | The ordered |
| `marker` | `string` | Yes | The marker |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitListStart()
[Section titled “visitListStart()”](#visitliststart)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```typescript
visitListStart(ctx: NodeContext, ordered: boolean): VisitResult
```
**Example:**
```typescript
const result = instance.visitListStart(new NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean` | Yes | The ordered |
**Returns:** `VisitResult`
###### visitListEnd()
[Section titled “visitListEnd()”](#visitlistend)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```typescript
visitListEnd(ctx: NodeContext, ordered: boolean, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitListEnd(new NodeContext(), true, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean` | Yes | The ordered |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### visitTableStart()
[Section titled “visitTableStart()”](#visittablestart)
Called before processing a table `<table>`.
**Signature:**
```typescript
visitTableStart(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitTableStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitTableRow()
[Section titled “visitTableRow()”](#visittablerow)
Visit table rows `<tr>`.
**Signature:**
```typescript
visitTableRow(ctx: NodeContext, cells: Array<string>, isHeader: boolean): VisitResult
```
**Example:**
```typescript
const result = instance.visitTableRow(new NodeContext(), [], true);
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | --------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `cells` | `Array<string>` | Yes | The cells |
| `isHeader` | `boolean` | Yes | The is header |
**Returns:** `VisitResult`
###### visitTableEnd()
[Section titled “visitTableEnd()”](#visittableend)
Called after processing a table `</table>`.
**Signature:**
```typescript
visitTableEnd(ctx: NodeContext, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitTableEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### visitBlockquote()
[Section titled “visitBlockquote()”](#visitblockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```typescript
visitBlockquote(ctx: NodeContext, content: string, depth: number): VisitResult
```
**Example:**
```typescript
const result = instance.visitBlockquote(new NodeContext(), "value", 42);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `content` | `string` | Yes | The content |
| `depth` | `number` | Yes | The depth |
**Returns:** `VisitResult`
###### visitStrong()
[Section titled “visitStrong()”](#visitstrong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```typescript
visitStrong(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitStrong(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitEmphasis()
[Section titled “visitEmphasis()”](#visitemphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```typescript
visitEmphasis(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitEmphasis(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitStrikethrough()
[Section titled “visitStrikethrough()”](#visitstrikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```typescript
visitStrikethrough(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitStrikethrough(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitUnderline()
[Section titled “visitUnderline()”](#visitunderline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```typescript
visitUnderline(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitUnderline(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitSubscript()
[Section titled “visitSubscript()”](#visitsubscript)
Visit subscript elements `<sub>`.
**Signature:**
```typescript
visitSubscript(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitSubscript(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitSuperscript()
[Section titled “visitSuperscript()”](#visitsuperscript)
Visit superscript elements `<sup>`.
**Signature:**
```typescript
visitSuperscript(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitSuperscript(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitMark()
[Section titled “visitMark()”](#visitmark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```typescript
visitMark(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitMark(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitLineBreak()
[Section titled “visitLineBreak()”](#visitlinebreak)
Visit line break elements `<br>`.
**Signature:**
```typescript
visitLineBreak(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitLineBreak(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitHorizontalRule()
[Section titled “visitHorizontalRule()”](#visithorizontalrule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```typescript
visitHorizontalRule(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitHorizontalRule(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitCustomElement()
[Section titled “visitCustomElement()”](#visitcustomelement)
Visit custom elements (web components) or unknown tags.
**Signature:**
```typescript
visitCustomElement(ctx: NodeContext, tagName: string, html: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitCustomElement(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `tagName` | `string` | Yes | The tag name |
| `html` | `string` | Yes | The html |
**Returns:** `VisitResult`
###### visitDefinitionListStart()
[Section titled “visitDefinitionListStart()”](#visitdefinitionliststart)
Visit definition list `<dl>`.
**Signature:**
```typescript
visitDefinitionListStart(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitDefinitionListStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitDefinitionTerm()
[Section titled “visitDefinitionTerm()”](#visitdefinitionterm)
Visit definition term `<dt>`.
**Signature:**
```typescript
visitDefinitionTerm(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitDefinitionTerm(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionDescription()
[Section titled “visitDefinitionDescription()”](#visitdefinitiondescription)
Visit definition description `<dd>`.
**Signature:**
```typescript
visitDefinitionDescription(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitDefinitionDescription(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionListEnd()
[Section titled “visitDefinitionListEnd()”](#visitdefinitionlistend)
Called after processing a definition list `</dl>`.
**Signature:**
```typescript
visitDefinitionListEnd(ctx: NodeContext, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitDefinitionListEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### visitForm()
[Section titled “visitForm()”](#visitform)
Visit form elements `<form>`.
**Signature:**
```typescript
visitForm(ctx: NodeContext, action: string, method: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitForm(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `action` | `string \| null` | No | The action |
| `method` | `string \| null` | No | The method |
**Returns:** `VisitResult`
###### visitInput()
[Section titled “visitInput()”](#visitinput)
Visit input elements `<input>`.
**Signature:**
```typescript
visitInput(ctx: NodeContext, inputType: string, name: string, value: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitInput(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `inputType` | `string` | Yes | The input type |
| `name` | `string \| null` | No | The name |
| `value` | `string \| null` | No | The value |
**Returns:** `VisitResult`
###### visitButton()
[Section titled “visitButton()”](#visitbutton)
Visit button elements `<button>`.
**Signature:**
```typescript
visitButton(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitButton(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitAudio()
[Section titled “visitAudio()”](#visitaudio)
Visit audio elements `<audio>`.
**Signature:**
```typescript
visitAudio(ctx: NodeContext, src: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitAudio(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `string \| null` | No | The src |
**Returns:** `VisitResult`
###### visitVideo()
[Section titled “visitVideo()”](#visitvideo)
Visit video elements `<video>`.
**Signature:**
```typescript
visitVideo(ctx: NodeContext, src: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitVideo(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `string \| null` | No | The src |
**Returns:** `VisitResult`
###### visitIframe()
[Section titled “visitIframe()”](#visitiframe)
Visit iframe elements `<iframe>`.
**Signature:**
```typescript
visitIframe(ctx: NodeContext, src: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitIframe(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `string \| null` | No | The src |
**Returns:** `VisitResult`
###### visitDetails()
[Section titled “visitDetails()”](#visitdetails)
Visit details elements `<details>`.
**Signature:**
```typescript
visitDetails(ctx: NodeContext, open: boolean): VisitResult
```
**Example:**
```typescript
const result = instance.visitDetails(new NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `open` | `boolean` | Yes | The open |
**Returns:** `VisitResult`
###### visitSummary()
[Section titled “visitSummary()”](#visitsummary)
Visit summary elements `<summary>`.
**Signature:**
```typescript
visitSummary(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitSummary(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureStart()
[Section titled “visitFigureStart()”](#visitfigurestart)
Visit figure elements `<figure>`.
**Signature:**
```typescript
visitFigureStart(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitFigureStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitFigcaption()
[Section titled “visitFigcaption()”](#visitfigcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```typescript
visitFigcaption(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitFigcaption(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureEnd()
[Section titled “visitFigureEnd()”](#visitfigureend)
Called after processing a figure `</figure>`.
**Signature:**
```typescript
visitFigureEnd(ctx: NodeContext, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitFigureEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `string[][]` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | -------- | ------- | ----------------- |
| `width` | `number` | — | Width in pixels. |
| `height` | `number` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ------------------------- | ------- | ------------------------------------------------------- |
| `src` | `string` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `string \| null` | `null` | Alternative text from alt attribute (for accessibility) |
| `title` | `string \| null` | `null` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions \| null` | `null` | Image dimensions in pixels, if available. |
| `imageType` | `ImageType` | — | Image type classification |
| `attributes` | `Record<string, string>` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ------------------------ | ------- | ------------------------------------------------------------------- |
| `href` | `string` | — | The href URL value |
| `text` | `string` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `string \| null` | `null` | Optional title attribute (often shown as tooltip) |
| `linkType` | `LinkType` | — | Link type classification |
| `rel` | `Array<string>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `Record<string, string>` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `string` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `string` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `Record<string, string>`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| --------------- | ---------------- | ------- | ------------------------------------------------------- |
| `nodeType` | `NodeType` | — | Coarse-grained node type classification |
| `tagName` | `string` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `number` | — | Depth in the DOM tree (0 = root) |
| `indexInParent` | `number` | — | Index among siblings (0-based) |
| `parentTag` | `string \| null` | `null` | Parent element’s tag name (None if root) |
| `isInline` | `boolean` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------ | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `enabled` | `boolean` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset.Standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `removeNavigation` | `boolean` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `removeForms` | `boolean` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `string` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | --------------------------------------------------------------- |
| `dataType` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `rawJson` | `string` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schemaType` | `string \| null` | `null` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `string` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `number` | — | Number of rows. |
| `cols` | `number` | — | Number of columns. |
| `cells` | `Array<GridCell>` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `number` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `number` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------- | ---------------------------------------------------- |
| `LeftToRight` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Anchor` | Anchor link within same document (href starts with #) |
| `Internal` | Internal link within same domain |
| `External` | External link to different domain |
| `Email` | Email link (mailto:) |
| `Phone` | Phone link (tel:) |
| `Other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ----------- | -------------------------------------------------- |
| `DataUri` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | Inline SVG element |
| `External` | External image URL (http/https) |
| `Relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JsonLd` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `Rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `Tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | A heading element (h1-h6). — Fields: `level`: `number`, `text`: `string` |
| `Paragraph` | A paragraph of text. — Fields: `text`: `string` |
| `List` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `boolean` |
| `ListItem` | A single list item. — Fields: `text`: `string` |
| `Table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `Image` | An image element. — Fields: `description`: `string`, `src`: `string`, `imageIndex`: `number` |
| `Code` | A code block or inline code. — Fields: `text`: `string`, `language`: `string` |
| `Quote` | A block quote container. |
| `DefinitionList` | A definition list container. |
| `DefinitionItem` | A definition list entry with term and description. — Fields: `term`: `string`, `definition`: `string` |
| `RawBlock` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `string`, `content`: `string` |
| `MetadataBlock` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `Array<MetadataEntry>` |
| `Group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `string`, `headingLevel`: `number`, `headingText`: `string` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | Bold / strong emphasis. |
| `Italic` | Italic / emphasis. |
| `Underline` | Underline. |
| `Strikethrough` | Strikethrough / deleted text. |
| `Code` | Inline code. |
| `Subscript` | Subscript text. |
| `Superscript` | Superscript text. |
| `Highlight` | Highlighted / marked text. |
| `Link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `string`, `title`: `string` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | The input was truncated due to size limits. |
| `MalformedHtml` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ----------------------- | ---------------------------------------------- |
| `Text` | Text node (most frequent - 100+ per document) |
| `Element` | Generic element node |
| `Heading` | Heading elements (h1-h6) |
| `Paragraph` | Paragraph element |
| `Div` | Generic div container |
| `Blockquote` | Blockquote element |
| `Pre` | Preformatted text block |
| `Hr` | Horizontal rule |
| `List` | Ordered or unordered list (ul, ol) |
| `ListItem` | List item (li) |
| `DefinitionList` | Definition list (dl) |
| `DefinitionTerm` | Definition term (dt) |
| `DefinitionDescription` | Definition description (dd) |
| `Table` | Table element |
| `TableRow` | Table row (tr) |
| `TableCell` | Table cell (td, th) |
| `TableHeader` | Table header cell (th) |
| `TableBody` | Table body (tbody) |
| `TableHead` | Table head (thead) |
| `TableFoot` | Table foot (tfoot) |
| `Link` | Anchor link (a) |
| `Image` | Image (img) |
| `Strong` | Strong/bold (strong, b) |
| `Em` | Emphasis/italic (em, i) |
| `Code` | Inline code (code) |
| `Strikethrough` | Strikethrough (s, del, strike) |
| `Underline` | Underline (u, ins) |
| `Subscript` | Subscript (sub) |
| `Superscript` | Superscript (sup) |
| `Mark` | Mark/highlight (mark) |
| `Small` | Small text (small) |
| `Br` | Line break (br) |
| `Span` | Span element |
| `Article` | Article element |
| `Section` | Section element |
| `Nav` | Navigation element |
| `Aside` | Aside element |
| `Header` | Header element |
| `Footer` | Footer element |
| `Main` | Main element |
| `Figure` | Figure element |
| `Figcaption` | Figure caption |
| `Time` | Time element |
| `Details` | Details element |
| `Summary` | Summary element |
| `Form` | Form element |
| `Input` | Input element |
| `Select` | Select element |
| `Option` | Option element |
| `Button` | Button element |
| `Textarea` | Textarea element |
| `Label` | Label element |
| `Fieldset` | Fieldset element |
| `Legend` | Legend element |
| `Audio` | Audio element |
| `Video` | Video element |
| `Picture` | Picture element |
| `Source` | Source element |
| `Iframe` | Iframe element |
| `Svg` | SVG element |
| `Canvas` | Canvas element |
| `Ruby` | Ruby annotation |
| `Rt` | Ruby text |
| `Rp` | Ruby parenthesis |
| `Abbr` | Abbreviation |
| `Kbd` | Keyboard input |
| `Samp` | Sample output |
| `Var` | Variable |
| `Cite` | Citation |
| `Q` | Quote |
| `Del` | Deleted text |
| `Ins` | Inserted text |
| `Data` | Data element |
| `Meter` | Meter element |
| `Progress` | Progress element |
| `Output` | Output element |
| `Template` | Template element |
| `Slot` | Slot element |
| `Html` | HTML root element |
| `Head` | Head element |
| `Body` | Body element |
| `Title` | Title element |
| `Meta` | Meta element |
| `LinkTag` | Link element (not anchor) |
| `Style` | Style element |
| `Script` | Script element |
| `Base` | Base element |
| `Custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Continue` | Continue with default conversion behavior |
| `Custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `string` |
| `Skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PreserveHtml` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `Error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `string` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
Errors are thrown as plain `Error` objects with descriptive messages.
| Variant | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseError` | HTML parsing error |
| `SanitizationError` | HTML sanitization error |
| `ConfigError` | Invalid configuration |
| `IoError` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `Panic` | Internal error caught during conversion |
| `InvalidInput` | Invalid input data |
| `InputTooLarge` | Input exceeds the configured byte limit. |
| `Other` | Generic conversion error |
***
# WebAssembly API Reference
## WebAssembly API Reference v3.17.2
[Section titled “WebAssembly API Reference v3.17.2”](#webassembly-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```typescript
function convert(html: string, options?: ConversionOptions): ConversionResult
```
**Example:**
```typescript
const result = convert("value", new ConversionOptions());
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------------------- | -------- | ------------------ |
| `html` | `string` | Yes | The html |
| `options` | `ConversionOptions \| null` | No | The options to use |
**Returns:** `ConversionResult`
**Errors:** Throws `Error` with a descriptive message.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ---------------------------- | ----------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `headingStyle` | `HeadingStyle` | `HeadingStyle.Atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `listIndentType` | `ListIndentType` | `ListIndentType.Spaces` | How to indent nested list items (spaces or tab). |
| `listIndentWidth` | `number` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `string` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strongEmSymbol` | `string` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escapeAsterisks` | `boolean` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escapeUnderscores` | `boolean` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escapeMisc` | `boolean` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escapeAscii` | `boolean` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `codeLanguage` | `string` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `boolean` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expandAbbreviations` | `boolean` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `includeBlockquoteCitations` | `boolean` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `defaultTitle` | `boolean` | `false` | Emit a default title when no `<title>` tag is present. |
| `brInTables` | `boolean` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compactTables` | `boolean` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlightStyle` | `HighlightStyle` | `HighlightStyle.DoubleEqual` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extractMetadata` | `boolean` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespaceMode` | `WhitespaceMode` | `WhitespaceMode.Normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `stripNewlines` | `boolean` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `boolean` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrapWidth` | `number` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convertAsInline` | `boolean` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `subSymbol` | `string` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `supSymbol` | `string` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newlineStyle` | `NewlineStyle` | `NewlineStyle.Spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `codeBlockStyle` | `CodeBlockStyle` | `CodeBlockStyle.Backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keepInlineImagesIn` | `Array<string>` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `string` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `boolean` | `false` | Emit debug information during conversion. |
| `stripTags` | `Array<string>` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserveTags` | `Array<string>` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skipImages` | `boolean` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inlineDataMedia` | `InlineDataMedia` | `InlineDataMedia.Keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hiddenContent` | `HiddenContent` | `HiddenContent.Drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `urlEscapeStyle` | `UrlEscapeStyle` | `UrlEscapeStyle.Angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `linkStyle` | `LinkStyle` | `LinkStyle.Inline` | Link rendering style (inline or reference). |
| `outputFormat` | `OutputFormat` | `OutputFormat.Markdown` | Target output format (Markdown, plain text, etc.). |
| `includeDocumentStructure` | `boolean` | `false` | Include structured document tree in result. |
| `extractImages` | `boolean` | `false` | Extract inline images from data URIs and SVGs. |
| `maxImageSize` | `number` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `maxInputSize` | `number \| null` | `null` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `null`. Set `Some(bytes)` to choose another limit or `null` to disable it. |
| `captureSvg` | `boolean` | `false` | Capture SVG elements as images. |
| `inferDimensions` | `boolean` | `true` | Infer image dimensions from data. |
| `maxDepth` | `number \| null` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `excludeSelectors` | `Array<string>` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tierStrategy` | `TierStrategy` | `TierStrategy.Auto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `baseUrl` | `string \| null` | `null` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `null` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle \| null` | `null` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `string \| null` | `null` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure \| null` | `null` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `null` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `Array<TableData>` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `Array<ProcessingWarning>` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| --------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `string \| null` | `null` | Document title from `<title>` tag |
| `description` | `string \| null` | `null` | Document description from `<meta name="description">` tag |
| `keywords` | `Array<string>` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `string \| null` | `null` | Document author from `<meta name="author">` tag |
| `canonicalUrl` | `string \| null` | `null` | Canonical URL from `<link rel="canonical">` tag |
| `baseHref` | `string \| null` | `null` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `string \| null` | `null` | Document language from `lang` attribute |
| `textDirection` | `TextDirection \| null` | `null` | Document text direction from `dir` attribute |
| `openGraph` | `Record<string, string>` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitterCard` | `Record<string, string>` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `metaTags` | `Record<string, string>` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | -------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `number \| null` | `null` | Index of the parent node (None for root nodes). |
| `children` | `Array<number>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `Array<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `Record<string, string> \| null` | `null` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `null` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| -------------- | --------------------- | ------- | --------------------------------------------------- |
| `nodes` | `Array<DocumentNode>` | — | All nodes in document reading order. |
| `sourceFormat` | `string \| null` | `null` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ---------- | --------- | ---------------------- | ---------------------------------------------- |
| `content` | `string` | — | The text content of the cell. |
| `row` | `number` | — | 0-indexed row position. |
| `col` | `number` | — | 0-indexed column position. |
| `rowSpan` | `number` | `1` | Number of rows this cell spans (default 1). |
| `colSpan` | `number` | `1` | Number of columns this cell spans (default 1). |
| `isHeader` | `boolean` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------ | ---------------- | ------- | ----------------------------------------- |
| `level` | `number` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `string` | — | Normalized text content of the header |
| `id` | `string \| null` | `null` | HTML id attribute if present |
| `depth` | `number` | — | Document tree depth at the header element |
| `htmlOffset` | `number` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ---------------- | ----------------------- | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `Array<HeaderMetadata>` | `[]` | Extracted header elements with hierarchy |
| `links` | `Array<LinkMetadata>` | `[]` | Extracted hyperlinks with type classification |
| `images` | `Array<ImageMetadata>` | `[]` | Extracted images with source and dimensions |
| `structuredData` | `Array<StructuredData>` | `[]` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### visitText()
[Section titled “visitText()”](#visittext)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```typescript
visitText(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitText(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitElementStart()
[Section titled “visitElementStart()”](#visitelementstart)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```typescript
visitElementStart(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitElementStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitElementEnd()
[Section titled “visitElementEnd()”](#visitelementend)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```typescript
visitElementEnd(ctx: NodeContext, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitElementEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### visitLink()
[Section titled “visitLink()”](#visitlink)
Visit anchor links `<a href="...">`.
**Signature:**
```typescript
visitLink(ctx: NodeContext, href: string, text: string, title: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitLink(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `href` | `string` | Yes | The href |
| `text` | `string` | Yes | The text |
| `title` | `string \| null` | No | The title |
**Returns:** `VisitResult`
###### visitImage()
[Section titled “visitImage()”](#visitimage)
Visit images `<img src="...">`.
**Signature:**
```typescript
visitImage(ctx: NodeContext, src: string, alt: string, title: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitImage(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `string` | Yes | The src |
| `alt` | `string` | Yes | The alt |
| `title` | `string \| null` | No | The title |
**Returns:** `VisitResult`
###### visitHeading()
[Section titled “visitHeading()”](#visitheading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```typescript
visitHeading(ctx: NodeContext, level: number, text: string, id: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitHeading(new NodeContext(), 42, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `level` | `number` | Yes | The level |
| `text` | `string` | Yes | The text |
| `id` | `string \| null` | No | The id |
**Returns:** `VisitResult`
###### visitCodeBlock()
[Section titled “visitCodeBlock()”](#visitcodeblock)
Visit code blocks `<pre><code>`.
**Signature:**
```typescript
visitCodeBlock(ctx: NodeContext, lang: string, code: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitCodeBlock(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `lang` | `string \| null` | No | The lang |
| `code` | `string` | Yes | The code |
**Returns:** `VisitResult`
###### visitCodeInline()
[Section titled “visitCodeInline()”](#visitcodeinline)
Visit inline code `<code>`.
**Signature:**
```typescript
visitCodeInline(ctx: NodeContext, code: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitCodeInline(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `code` | `string` | Yes | The code |
**Returns:** `VisitResult`
###### visitListItem()
[Section titled “visitListItem()”](#visitlistitem)
Visit list items `<li>`.
**Signature:**
```typescript
visitListItem(ctx: NodeContext, ordered: boolean, marker: string, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitListItem(new NodeContext(), true, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean` | Yes | The ordered |
| `marker` | `string` | Yes | The marker |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitListStart()
[Section titled “visitListStart()”](#visitliststart)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```typescript
visitListStart(ctx: NodeContext, ordered: boolean): VisitResult
```
**Example:**
```typescript
const result = instance.visitListStart(new NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean` | Yes | The ordered |
**Returns:** `VisitResult`
###### visitListEnd()
[Section titled “visitListEnd()”](#visitlistend)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```typescript
visitListEnd(ctx: NodeContext, ordered: boolean, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitListEnd(new NodeContext(), true, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `ordered` | `boolean` | Yes | The ordered |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### visitTableStart()
[Section titled “visitTableStart()”](#visittablestart)
Called before processing a table `<table>`.
**Signature:**
```typescript
visitTableStart(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitTableStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitTableRow()
[Section titled “visitTableRow()”](#visittablerow)
Visit table rows `<tr>`.
**Signature:**
```typescript
visitTableRow(ctx: NodeContext, cells: Array<string>, isHeader: boolean): VisitResult
```
**Example:**
```typescript
const result = instance.visitTableRow(new NodeContext(), [], true);
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | --------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `cells` | `Array<string>` | Yes | The cells |
| `isHeader` | `boolean` | Yes | The is header |
**Returns:** `VisitResult`
###### visitTableEnd()
[Section titled “visitTableEnd()”](#visittableend)
Called after processing a table `</table>`.
**Signature:**
```typescript
visitTableEnd(ctx: NodeContext, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitTableEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### visitBlockquote()
[Section titled “visitBlockquote()”](#visitblockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```typescript
visitBlockquote(ctx: NodeContext, content: string, depth: number): VisitResult
```
**Example:**
```typescript
const result = instance.visitBlockquote(new NodeContext(), "value", 42);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `content` | `string` | Yes | The content |
| `depth` | `number` | Yes | The depth |
**Returns:** `VisitResult`
###### visitStrong()
[Section titled “visitStrong()”](#visitstrong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```typescript
visitStrong(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitStrong(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitEmphasis()
[Section titled “visitEmphasis()”](#visitemphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```typescript
visitEmphasis(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitEmphasis(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitStrikethrough()
[Section titled “visitStrikethrough()”](#visitstrikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```typescript
visitStrikethrough(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitStrikethrough(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitUnderline()
[Section titled “visitUnderline()”](#visitunderline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```typescript
visitUnderline(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitUnderline(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitSubscript()
[Section titled “visitSubscript()”](#visitsubscript)
Visit subscript elements `<sub>`.
**Signature:**
```typescript
visitSubscript(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitSubscript(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitSuperscript()
[Section titled “visitSuperscript()”](#visitsuperscript)
Visit superscript elements `<sup>`.
**Signature:**
```typescript
visitSuperscript(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitSuperscript(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitMark()
[Section titled “visitMark()”](#visitmark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```typescript
visitMark(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitMark(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitLineBreak()
[Section titled “visitLineBreak()”](#visitlinebreak)
Visit line break elements `<br>`.
**Signature:**
```typescript
visitLineBreak(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitLineBreak(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitHorizontalRule()
[Section titled “visitHorizontalRule()”](#visithorizontalrule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```typescript
visitHorizontalRule(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitHorizontalRule(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitCustomElement()
[Section titled “visitCustomElement()”](#visitcustomelement)
Visit custom elements (web components) or unknown tags.
**Signature:**
```typescript
visitCustomElement(ctx: NodeContext, tagName: string, html: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitCustomElement(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `tagName` | `string` | Yes | The tag name |
| `html` | `string` | Yes | The html |
**Returns:** `VisitResult`
###### visitDefinitionListStart()
[Section titled “visitDefinitionListStart()”](#visitdefinitionliststart)
Visit definition list `<dl>`.
**Signature:**
```typescript
visitDefinitionListStart(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitDefinitionListStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitDefinitionTerm()
[Section titled “visitDefinitionTerm()”](#visitdefinitionterm)
Visit definition term `<dt>`.
**Signature:**
```typescript
visitDefinitionTerm(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitDefinitionTerm(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionDescription()
[Section titled “visitDefinitionDescription()”](#visitdefinitiondescription)
Visit definition description `<dd>`.
**Signature:**
```typescript
visitDefinitionDescription(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitDefinitionDescription(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitDefinitionListEnd()
[Section titled “visitDefinitionListEnd()”](#visitdefinitionlistend)
Called after processing a definition list `</dl>`.
**Signature:**
```typescript
visitDefinitionListEnd(ctx: NodeContext, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitDefinitionListEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
###### visitForm()
[Section titled “visitForm()”](#visitform)
Visit form elements `<form>`.
**Signature:**
```typescript
visitForm(ctx: NodeContext, action: string, method: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitForm(new NodeContext(), "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `action` | `string \| null` | No | The action |
| `method` | `string \| null` | No | The method |
**Returns:** `VisitResult`
###### visitInput()
[Section titled “visitInput()”](#visitinput)
Visit input elements `<input>`.
**Signature:**
```typescript
visitInput(ctx: NodeContext, inputType: string, name: string, value: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitInput(new NodeContext(), "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `inputType` | `string` | Yes | The input type |
| `name` | `string \| null` | No | The name |
| `value` | `string \| null` | No | The value |
**Returns:** `VisitResult`
###### visitButton()
[Section titled “visitButton()”](#visitbutton)
Visit button elements `<button>`.
**Signature:**
```typescript
visitButton(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitButton(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitAudio()
[Section titled “visitAudio()”](#visitaudio)
Visit audio elements `<audio>`.
**Signature:**
```typescript
visitAudio(ctx: NodeContext, src: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitAudio(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `string \| null` | No | The src |
**Returns:** `VisitResult`
###### visitVideo()
[Section titled “visitVideo()”](#visitvideo)
Visit video elements `<video>`.
**Signature:**
```typescript
visitVideo(ctx: NodeContext, src: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitVideo(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `string \| null` | No | The src |
**Returns:** `VisitResult`
###### visitIframe()
[Section titled “visitIframe()”](#visitiframe)
Visit iframe elements `<iframe>`.
**Signature:**
```typescript
visitIframe(ctx: NodeContext, src: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitIframe(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ---------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `src` | `string \| null` | No | The src |
**Returns:** `VisitResult`
###### visitDetails()
[Section titled “visitDetails()”](#visitdetails)
Visit details elements `<details>`.
**Signature:**
```typescript
visitDetails(ctx: NodeContext, open: boolean): VisitResult
```
**Example:**
```typescript
const result = instance.visitDetails(new NodeContext(), true);
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `open` | `boolean` | Yes | The open |
**Returns:** `VisitResult`
###### visitSummary()
[Section titled “visitSummary()”](#visitsummary)
Visit summary elements `<summary>`.
**Signature:**
```typescript
visitSummary(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitSummary(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureStart()
[Section titled “visitFigureStart()”](#visitfigurestart)
Visit figure elements `<figure>`.
**Signature:**
```typescript
visitFigureStart(ctx: NodeContext): VisitResult
```
**Example:**
```typescript
const result = instance.visitFigureStart(new NodeContext());
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
**Returns:** `VisitResult`
###### visitFigcaption()
[Section titled “visitFigcaption()”](#visitfigcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```typescript
visitFigcaption(ctx: NodeContext, text: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitFigcaption(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `text` | `string` | Yes | The text |
**Returns:** `VisitResult`
###### visitFigureEnd()
[Section titled “visitFigureEnd()”](#visitfigureend)
Called after processing a figure `</figure>`.
**Signature:**
```typescript
visitFigureEnd(ctx: NodeContext, output: string): VisitResult
```
**Example:**
```typescript
const result = instance.visitFigureEnd(new NodeContext(), "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------------- | -------- | ---------------- |
| `ctx` | `NodeContext` | Yes | The node context |
| `output` | `string` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `string[][]` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | -------- | ------- | ----------------- |
| `width` | `number` | — | Width in pixels. |
| `height` | `number` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ------------------------- | ------- | ------------------------------------------------------- |
| `src` | `string` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `string \| null` | `null` | Alternative text from alt attribute (for accessibility) |
| `title` | `string \| null` | `null` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions \| null` | `null` | Image dimensions in pixels, if available. |
| `imageType` | `ImageType` | — | Image type classification |
| `attributes` | `Record<string, string>` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ------------------------ | ------- | ------------------------------------------------------------------- |
| `href` | `string` | — | The href URL value |
| `text` | `string` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `string \| null` | `null` | Optional title attribute (often shown as tooltip) |
| `linkType` | `LinkType` | — | Link type classification |
| `rel` | `Array<string>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `Record<string, string>` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `string` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `string` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `Record<string, string>`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| --------------- | ---------------- | ------- | ------------------------------------------------------- |
| `nodeType` | `NodeType` | — | Coarse-grained node type classification |
| `tagName` | `string` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `number` | — | Depth in the DOM tree (0 = root) |
| `indexInParent` | `number` | — | Index among siblings (0-based) |
| `parentTag` | `string \| null` | `null` | Parent element’s tag name (None if root) |
| `isInline` | `boolean` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------ | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `enabled` | `boolean` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset.Standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `removeNavigation` | `boolean` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `removeForms` | `boolean` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `string` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------ | -------------------- | ------- | --------------------------------------------------------------- |
| `dataType` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `rawJson` | `string` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schemaType` | `string \| null` | `null` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `string` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `number` | — | Number of rows. |
| `cols` | `number` | — | Number of columns. |
| `cells` | `Array<GridCell>` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `number` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `number` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| ------------- | ---------------------------------------------------- |
| `LeftToRight` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Anchor` | Anchor link within same document (href starts with #) |
| `Internal` | Internal link within same domain |
| `External` | External link to different domain |
| `Email` | Email link (mailto:) |
| `Phone` | Phone link (tel:) |
| `Other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ----------- | -------------------------------------------------- |
| `DataUri` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | Inline SVG element |
| `External` | External image URL (http/https) |
| `Relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `JsonLd` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `Rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `Tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | A heading element (h1-h6). — Fields: `level`: `number`, `text`: `string` |
| `Paragraph` | A paragraph of text. — Fields: `text`: `string` |
| `List` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `boolean` |
| `ListItem` | A single list item. — Fields: `text`: `string` |
| `Table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `Image` | An image element. — Fields: `description`: `string`, `src`: `string`, `imageIndex`: `number` |
| `Code` | A code block or inline code. — Fields: `text`: `string`, `language`: `string` |
| `Quote` | A block quote container. |
| `DefinitionList` | A definition list container. |
| `DefinitionItem` | A definition list entry with term and description. — Fields: `term`: `string`, `definition`: `string` |
| `RawBlock` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `string`, `content`: `string` |
| `MetadataBlock` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `Array<MetadataEntry>` |
| `Group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `string`, `headingLevel`: `number`, `headingText`: `string` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | Bold / strong emphasis. |
| `Italic` | Italic / emphasis. |
| `Underline` | Underline. |
| `Strikethrough` | Strikethrough / deleted text. |
| `Code` | Inline code. |
| `Subscript` | Subscript text. |
| `Superscript` | Superscript text. |
| `Highlight` | Highlighted / marked text. |
| `Link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `string`, `title`: `string` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | The input was truncated due to size limits. |
| `MalformedHtml` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ----------------------- | ---------------------------------------------- |
| `Text` | Text node (most frequent - 100+ per document) |
| `Element` | Generic element node |
| `Heading` | Heading elements (h1-h6) |
| `Paragraph` | Paragraph element |
| `Div` | Generic div container |
| `Blockquote` | Blockquote element |
| `Pre` | Preformatted text block |
| `Hr` | Horizontal rule |
| `List` | Ordered or unordered list (ul, ol) |
| `ListItem` | List item (li) |
| `DefinitionList` | Definition list (dl) |
| `DefinitionTerm` | Definition term (dt) |
| `DefinitionDescription` | Definition description (dd) |
| `Table` | Table element |
| `TableRow` | Table row (tr) |
| `TableCell` | Table cell (td, th) |
| `TableHeader` | Table header cell (th) |
| `TableBody` | Table body (tbody) |
| `TableHead` | Table head (thead) |
| `TableFoot` | Table foot (tfoot) |
| `Link` | Anchor link (a) |
| `Image` | Image (img) |
| `Strong` | Strong/bold (strong, b) |
| `Em` | Emphasis/italic (em, i) |
| `Code` | Inline code (code) |
| `Strikethrough` | Strikethrough (s, del, strike) |
| `Underline` | Underline (u, ins) |
| `Subscript` | Subscript (sub) |
| `Superscript` | Superscript (sup) |
| `Mark` | Mark/highlight (mark) |
| `Small` | Small text (small) |
| `Br` | Line break (br) |
| `Span` | Span element |
| `Article` | Article element |
| `Section` | Section element |
| `Nav` | Navigation element |
| `Aside` | Aside element |
| `Header` | Header element |
| `Footer` | Footer element |
| `Main` | Main element |
| `Figure` | Figure element |
| `Figcaption` | Figure caption |
| `Time` | Time element |
| `Details` | Details element |
| `Summary` | Summary element |
| `Form` | Form element |
| `Input` | Input element |
| `Select` | Select element |
| `Option` | Option element |
| `Button` | Button element |
| `Textarea` | Textarea element |
| `Label` | Label element |
| `Fieldset` | Fieldset element |
| `Legend` | Legend element |
| `Audio` | Audio element |
| `Video` | Video element |
| `Picture` | Picture element |
| `Source` | Source element |
| `Iframe` | Iframe element |
| `Svg` | SVG element |
| `Canvas` | Canvas element |
| `Ruby` | Ruby annotation |
| `Rt` | Ruby text |
| `Rp` | Ruby parenthesis |
| `Abbr` | Abbreviation |
| `Kbd` | Keyboard input |
| `Samp` | Sample output |
| `Var` | Variable |
| `Cite` | Citation |
| `Q` | Quote |
| `Del` | Deleted text |
| `Ins` | Inserted text |
| `Data` | Data element |
| `Meter` | Meter element |
| `Progress` | Progress element |
| `Output` | Output element |
| `Template` | Template element |
| `Slot` | Slot element |
| `Html` | HTML root element |
| `Head` | Head element |
| `Body` | Body element |
| `Title` | Title element |
| `Meta` | Meta element |
| `LinkTag` | Link element (not anchor) |
| `Style` | Style element |
| `Script` | Script element |
| `Base` | Base element |
| `Custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Continue` | Continue with default conversion behavior |
| `Custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `string` |
| `Skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PreserveHtml` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `Error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `string` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
Errors are thrown as plain `Error` objects with descriptive messages.
| Variant | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseError` | HTML parsing error |
| `SanitizationError` | HTML sanitization error |
| `ConfigError` | Invalid configuration |
| `IoError` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `Panic` | Internal error caught during conversion |
| `InvalidInput` | Invalid input data |
| `InputTooLarge` | Input exceeds the configured byte limit. |
| `Other` | Generic conversion error |
***
# Zig API Reference
## Zig API Reference v3.17.2
[Section titled “Zig API Reference v3.17.2”](#zig-api-reference-v3172)
### Functions
[Section titled “Functions”](#functions)
#### convert()
[Section titled “convert()”](#convert)
Convert HTML to Markdown, Djot, or plain text.
Returns a `ConversionResult` with converted content plus optional metadata, document structure, table data, inline images, and warnings depending on the enabled features and conversion options.
**Errors:**
Returns an error if the configured input-size limit is exceeded, HTML parsing fails, or the input contains invalid UTF-8.
##### Observability
[Section titled “Observability”](#observability)
Emits an `html_to_markdown.convert` span at `INFO` level with fields `input_len`, `output_format`, `wrap`, `extract_metadata`, `extract_images`, and `tier_strategy`. These field names are part of the public observability contract and are kept stable across releases. This crate never installs a `tracing` subscriber — attach one in the consuming application to observe these spans and events.
**Signature:**
```zig
pub fn convert(html: []const u8, options: ?[]const u8) ConversionError![]u8
```
**Example:**
```zig
const result = try convert("value", .{});
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | --------------- | -------- | ------------------ |
| `html` | `\[\]const u8` | Yes | The html |
| `options` | `?\[\]const u8` | No | The options to use |
**Returns:** `[]u8`
**Errors:** Throws `ConversionError`.
***
### Types
[Section titled “Types”](#types)
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ------------------------------ | ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading_style` | `HeadingStyle` | `HeadingStyle.atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `list_indent_type` | `ListIndentType` | `ListIndentType.spaces` | How to indent nested list items (spaces or tab). |
| `list_indent_width` | `u64` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `\[\]const u8` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strong_em_symbol` | `\[\]const u8` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escape_asterisks` | `bool` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escape_underscores` | `bool` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escape_misc` | `bool` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escape_ascii` | `bool` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `code_language` | `\[\]const u8` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `bool` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expand_abbreviations` | `bool` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `include_blockquote_citations` | `bool` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `default_title` | `bool` | `false` | Emit a default title when no `<title>` tag is present. |
| `br_in_tables` | `bool` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compact_tables` | `bool` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlight_style` | `HighlightStyle` | `HighlightStyle.double_equal` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extract_metadata` | `bool` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespace_mode` | `WhitespaceMode` | `WhitespaceMode.normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `strip_newlines` | `bool` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `bool` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrap_width` | `u64` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convert_as_inline` | `bool` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `sub_symbol` | `\[\]const u8` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `sup_symbol` | `\[\]const u8` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newline_style` | `NewlineStyle` | `NewlineStyle.spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `code_block_style` | `CodeBlockStyle` | `CodeBlockStyle.backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keep_inline_images_in` | `\[\]const \[\]const u8` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `\[\]const u8` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `bool` | `false` | Emit debug information during conversion. |
| `strip_tags` | `\[\]const \[\]const u8` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserve_tags` | `\[\]const \[\]const u8` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skip_images` | `bool` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inline_data_media` | `InlineDataMedia` | `InlineDataMedia.keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hidden_content` | `HiddenContent` | `HiddenContent.drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `url_escape_style` | `UrlEscapeStyle` | `UrlEscapeStyle.angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `link_style` | `LinkStyle` | `LinkStyle.inline` | Link rendering style (inline or reference). |
| `output_format` | `OutputFormat` | `OutputFormat.markdown` | Target output format (Markdown, plain text, etc.). |
| `include_document_structure` | `bool` | `false` | Include structured document tree in result. |
| `extract_images` | `bool` | `false` | Extract inline images from data URIs and SVGs. |
| `max_image_size` | `u64` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `max_input_size` | `u64?` | `null` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `null`. Set `Some(bytes)` to choose another limit or `null` to disable it. |
| `capture_svg` | `bool` | `false` | Capture SVG elements as images. |
| `infer_dimensions` | `bool` | `true` | Infer image dimensions from data. |
| `max_depth` | `u64?` | `null` | Maximum DOM traversal depth. `null` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `exclude_selectors` | `\[\]const \[\]const u8` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tier_strategy` | `TierStrategy` | `TierStrategy.auto` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `base_url` | `\[\]const u8?` | `null` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `null` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle?` | `null` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `\[\]const u8?` | `null` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure?` | `null` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `true`. `null` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `\[\]const TableData` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `true`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `\[\]const ProcessingWarning` | `[]` | Non-fatal processing warnings. |
***
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| ---------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `\[\]const u8?` | `null` | Document title from `<title>` tag |
| `description` | `\[\]const u8?` | `null` | Document description from `<meta name="description">` tag |
| `keywords` | `\[\]const \[\]const u8` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `\[\]const u8?` | `null` | Document author from `<meta name="author">` tag |
| `canonical_url` | `\[\]const u8?` | `null` | Canonical URL from `<link rel="canonical">` tag |
| `base_href` | `\[\]const u8?` | `null` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `\[\]const u8?` | `null` | Document language from `lang` attribute |
| `text_direction` | `TextDirection?` | `null` | Document text direction from `dir` attribute |
| `open_graph` | `std.StringHashMap(\[\]const u8)` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitter_card` | `std.StringHashMap(\[\]const u8)` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `meta_tags` | `std.StringHashMap(\[\]const u8)` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ---------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `\[\]const u8` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `u32?` | `null` | Index of the parent node (None for root nodes). |
| `children` | `\[\]const u32` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `\[\]const TextAnnotation` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `std.StringHashMap(\[\]const u8)?` | `null` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `null` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| --------------- | ------------------------ | ------- | --------------------------------------------------- |
| `nodes` | `\[\]const DocumentNode` | — | All nodes in document reading order. |
| `source_format` | `\[\]const u8?` | `null` | The source format (always “html” for this library). |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ----------- | -------------- | ---------------------- | ---------------------------------------------- |
| `content` | `\[\]const u8` | — | The text content of the cell. |
| `row` | `u32` | — | 0-indexed row position. |
| `col` | `u32` | — | 0-indexed column position. |
| `row_span` | `u32` | `1` | Number of rows this cell spans (default 1). |
| `col_span` | `u32` | `1` | Number of columns this cell spans (default 1). |
| `is_header` | `bool` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------- | --------------- | ------- | ----------------------------------------- |
| `level` | `u8` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `\[\]const u8` | — | Normalized text content of the header |
| `id` | `\[\]const u8?` | `null` | HTML id attribute if present |
| `depth` | `u64` | — | Document tree depth at the header element |
| `html_offset` | `u64` | — | Byte offset in original HTML document |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ----------------- | -------------------------- | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `\[\]const HeaderMetadata` | `[]` | Extracted header elements with hierarchy |
| `links` | `\[\]const LinkMetadata` | `[]` | Extracted hyperlinks with type classification |
| `images` | `\[\]const ImageMetadata` | `[]` | Extracted images with source and dimensions |
| `structured_data` | `\[\]const StructuredData` | `[]` | Extracted structured data blocks |
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
##### Methods
[Section titled “Methods”](#methods)
###### visit_text()
[Section titled “visit_text()”](#visit_text)
Visit text nodes (most frequent callback - \~100+ per document).
**Signature:**
```zig
pub fn visit_text(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_text(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_element_start()
[Section titled “visit_element_start()”](#visit_element_start)
Called before entering any element.
This is the first callback invoked for every HTML element, allowing visitors to implement generic element handling before tag-specific logic.
**Signature:**
```zig
pub fn visit_element_start(self: *const HtmlVisitor, ctx: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_element_start(.{});
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_element_end()
[Section titled “visit_element_end()”](#visit_element_end)
Called after exiting any element.
Receives the default markdown output that would be generated. Visitors can inspect or replace this output.
**Signature:**
```zig
pub fn visit_element_end(self: *const HtmlVisitor, ctx: []const u8, output: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_element_end(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `output` | `\[\]const u8` | Yes | The output |
**Returns:** `VisitResult`
###### visit_link()
[Section titled “visit_link()”](#visit_link)
Visit anchor links `<a href="...">`.
**Signature:**
```zig
pub fn visit_link(self: *const HtmlVisitor, ctx: []const u8, href: []const u8, text: []const u8, title: ?[]const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_link(.{}, "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | --------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `href` | `\[\]const u8` | Yes | The href |
| `text` | `\[\]const u8` | Yes | The text |
| `title` | `?\[\]const u8` | No | The title |
**Returns:** `VisitResult`
###### visit_image()
[Section titled “visit_image()”](#visit_image)
Visit images `<img src="...">`.
**Signature:**
```zig
pub fn visit_image(self: *const HtmlVisitor, ctx: []const u8, src: []const u8, alt: []const u8, title: ?[]const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_image(.{}, "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | --------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `src` | `\[\]const u8` | Yes | The src |
| `alt` | `\[\]const u8` | Yes | The alt |
| `title` | `?\[\]const u8` | No | The title |
**Returns:** `VisitResult`
###### visit_heading()
[Section titled “visit_heading()”](#visit_heading)
Visit heading elements `<h1>` through `<h6>`.
**Signature:**
```zig
pub fn visit_heading(self: *const HtmlVisitor, ctx: []const u8, level: u32, text: []const u8, id: ?[]const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_heading(.{}, 42, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------- | --------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `level` | `u32` | Yes | The level |
| `text` | `\[\]const u8` | Yes | The text |
| `id` | `?\[\]const u8` | No | The id |
**Returns:** `VisitResult`
###### visit_code_block()
[Section titled “visit_code_block()”](#visit_code_block)
Visit code blocks `<pre><code>`.
**Signature:**
```zig
pub fn visit_code_block(self: *const HtmlVisitor, ctx: []const u8, lang: ?[]const u8, code: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_code_block(.{}, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `lang` | `?\[\]const u8` | No | The lang |
| `code` | `\[\]const u8` | Yes | The code |
**Returns:** `VisitResult`
###### visit_code_inline()
[Section titled “visit_code_inline()”](#visit_code_inline)
Visit inline code `<code>`.
**Signature:**
```zig
pub fn visit_code_inline(self: *const HtmlVisitor, ctx: []const u8, code: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_code_inline(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `code` | `\[\]const u8` | Yes | The code |
**Returns:** `VisitResult`
###### visit_list_item()
[Section titled “visit_list_item()”](#visit_list_item)
Visit list items `<li>`.
**Signature:**
```zig
pub fn visit_list_item(self: *const HtmlVisitor, ctx: []const u8, ordered: bool, marker: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_list_item(.{}, true, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
| `marker` | `\[\]const u8` | Yes | The marker |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_list_start()
[Section titled “visit_list_start()”](#visit_list_start)
Called before processing a list `<ul>` or `<ol>`.
**Signature:**
```zig
pub fn visit_list_start(self: *const HtmlVisitor, ctx: []const u8, ordered: bool) VisitResult
```
**Example:**
```zig
const result = instance.visit_list_start(.{}, true);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
**Returns:** `VisitResult`
###### visit_list_end()
[Section titled “visit_list_end()”](#visit_list_end)
Called after processing a list `</ul>` or `</ol>`.
**Signature:**
```zig
pub fn visit_list_end(self: *const HtmlVisitor, ctx: []const u8, ordered: bool, output: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_list_end(.{}, true, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `ordered` | `bool` | Yes | The ordered |
| `output` | `\[\]const u8` | Yes | The output |
**Returns:** `VisitResult`
###### visit_table_start()
[Section titled “visit_table_start()”](#visit_table_start)
Called before processing a table `<table>`.
**Signature:**
```zig
pub fn visit_table_start(self: *const HtmlVisitor, ctx: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_table_start(.{});
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_table_row()
[Section titled “visit_table_row()”](#visit_table_row)
Visit table rows `<tr>`.
**Signature:**
```zig
pub fn visit_table_row(self: *const HtmlVisitor, ctx: []const u8, cells: []const u8, is_header: bool) VisitResult
```
**Example:**
```zig
const result = instance.visit_table_row(.{}, &[_]u8{}, true);
```
**Parameters:**
| Name | Type | Required | Description |
| ----------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `cells` | `\[\]const u8` | Yes | The cells |
| `is_header` | `bool` | Yes | The is header |
**Returns:** `VisitResult`
###### visit_table_end()
[Section titled “visit_table_end()”](#visit_table_end)
Called after processing a table `</table>`.
**Signature:**
```zig
pub fn visit_table_end(self: *const HtmlVisitor, ctx: []const u8, output: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_table_end(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `output` | `\[\]const u8` | Yes | The output |
**Returns:** `VisitResult`
###### visit_blockquote()
[Section titled “visit_blockquote()”](#visit_blockquote)
Visit blockquote elements `<blockquote>`.
**Signature:**
```zig
pub fn visit_blockquote(self: *const HtmlVisitor, ctx: []const u8, content: []const u8, depth: u64) VisitResult
```
**Example:**
```zig
const result = instance.visit_blockquote(.{}, "value", 42);
```
**Parameters:**
| Name | Type | Required | Description |
| --------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `content` | `\[\]const u8` | Yes | The content |
| `depth` | `u64` | Yes | The depth |
**Returns:** `VisitResult`
###### visit_strong()
[Section titled “visit_strong()”](#visit_strong)
Visit strong/bold elements `<strong>`, `<b>`.
**Signature:**
```zig
pub fn visit_strong(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_strong(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_emphasis()
[Section titled “visit_emphasis()”](#visit_emphasis)
Visit emphasis/italic elements `<em>`, `<i>`.
**Signature:**
```zig
pub fn visit_emphasis(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_emphasis(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_strikethrough()
[Section titled “visit_strikethrough()”](#visit_strikethrough)
Visit strikethrough elements `<s>`, `<del>`, `<strike>`.
**Signature:**
```zig
pub fn visit_strikethrough(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_strikethrough(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_underline()
[Section titled “visit_underline()”](#visit_underline)
Visit underline elements `<u>`, `<ins>`.
**Signature:**
```zig
pub fn visit_underline(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_underline(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_subscript()
[Section titled “visit_subscript()”](#visit_subscript)
Visit subscript elements `<sub>`.
**Signature:**
```zig
pub fn visit_subscript(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_subscript(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_superscript()
[Section titled “visit_superscript()”](#visit_superscript)
Visit superscript elements `<sup>`.
**Signature:**
```zig
pub fn visit_superscript(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_superscript(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_mark()
[Section titled “visit_mark()”](#visit_mark)
Visit mark/highlight elements `<mark>`.
**Signature:**
```zig
pub fn visit_mark(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_mark(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_line_break()
[Section titled “visit_line_break()”](#visit_line_break)
Visit line break elements `<br>`.
**Signature:**
```zig
pub fn visit_line_break(self: *const HtmlVisitor, ctx: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_line_break(.{});
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_horizontal_rule()
[Section titled “visit_horizontal_rule()”](#visit_horizontal_rule)
Visit horizontal rule elements `<hr>`.
**Signature:**
```zig
pub fn visit_horizontal_rule(self: *const HtmlVisitor, ctx: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_horizontal_rule(.{});
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_custom_element()
[Section titled “visit_custom_element()”](#visit_custom_element)
Visit custom elements (web components) or unknown tags.
**Signature:**
```zig
pub fn visit_custom_element(self: *const HtmlVisitor, ctx: []const u8, tag_name: []const u8, html: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_custom_element(.{}, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ---------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `tag_name` | `\[\]const u8` | Yes | The tag name |
| `html` | `\[\]const u8` | Yes | The html |
**Returns:** `VisitResult`
###### visit_definition_list_start()
[Section titled “visit_definition_list_start()”](#visit_definition_list_start)
Visit definition list `<dl>`.
**Signature:**
```zig
pub fn visit_definition_list_start(self: *const HtmlVisitor, ctx: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_definition_list_start(.{});
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_definition_term()
[Section titled “visit_definition_term()”](#visit_definition_term)
Visit definition term `<dt>`.
**Signature:**
```zig
pub fn visit_definition_term(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_definition_term(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_description()
[Section titled “visit_definition_description()”](#visit_definition_description)
Visit definition description `<dd>`.
**Signature:**
```zig
pub fn visit_definition_description(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_definition_description(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_definition_list_end()
[Section titled “visit_definition_list_end()”](#visit_definition_list_end)
Called after processing a definition list `</dl>`.
**Signature:**
```zig
pub fn visit_definition_list_end(self: *const HtmlVisitor, ctx: []const u8, output: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_definition_list_end(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `output` | `\[\]const u8` | Yes | The output |
**Returns:** `VisitResult`
###### visit_form()
[Section titled “visit_form()”](#visit_form)
Visit form elements `<form>`.
**Signature:**
```zig
pub fn visit_form(self: *const HtmlVisitor, ctx: []const u8, action: ?[]const u8, method: ?[]const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_form(.{}, "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | --------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `action` | `?\[\]const u8` | No | The action |
| `method` | `?\[\]const u8` | No | The method |
**Returns:** `VisitResult`
###### visit_input()
[Section titled “visit_input()”](#visit_input)
Visit input elements `<input>`.
**Signature:**
```zig
pub fn visit_input(self: *const HtmlVisitor, ctx: []const u8, input_type: []const u8, name: ?[]const u8, value: ?[]const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_input(.{}, "value", "value", "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------------ | --------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `input_type` | `\[\]const u8` | Yes | The input type |
| `name` | `?\[\]const u8` | No | The name |
| `value` | `?\[\]const u8` | No | The value |
**Returns:** `VisitResult`
###### visit_button()
[Section titled “visit_button()”](#visit_button)
Visit button elements `<button>`.
**Signature:**
```zig
pub fn visit_button(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_button(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_audio()
[Section titled “visit_audio()”](#visit_audio)
Visit audio elements `<audio>`.
**Signature:**
```zig
pub fn visit_audio(self: *const HtmlVisitor, ctx: []const u8, src: ?[]const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_audio(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `src` | `?\[\]const u8` | No | The src |
**Returns:** `VisitResult`
###### visit_video()
[Section titled “visit_video()”](#visit_video)
Visit video elements `<video>`.
**Signature:**
```zig
pub fn visit_video(self: *const HtmlVisitor, ctx: []const u8, src: ?[]const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_video(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `src` | `?\[\]const u8` | No | The src |
**Returns:** `VisitResult`
###### visit_iframe()
[Section titled “visit_iframe()”](#visit_iframe)
Visit iframe elements `<iframe>`.
**Signature:**
```zig
pub fn visit_iframe(self: *const HtmlVisitor, ctx: []const u8, src: ?[]const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_iframe(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | --------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `src` | `?\[\]const u8` | No | The src |
**Returns:** `VisitResult`
###### visit_details()
[Section titled “visit_details()”](#visit_details)
Visit details elements `<details>`.
**Signature:**
```zig
pub fn visit_details(self: *const HtmlVisitor, ctx: []const u8, open: bool) VisitResult
```
**Example:**
```zig
const result = instance.visit_details(.{}, true);
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `open` | `bool` | Yes | The open |
**Returns:** `VisitResult`
###### visit_summary()
[Section titled “visit_summary()”](#visit_summary)
Visit summary elements `<summary>`.
**Signature:**
```zig
pub fn visit_summary(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_summary(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_start()
[Section titled “visit_figure_start()”](#visit_figure_start)
Visit figure elements `<figure>`.
**Signature:**
```zig
pub fn visit_figure_start(self: *const HtmlVisitor, ctx: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_figure_start(.{});
```
**Parameters:**
| Name | Type | Required | Description |
| ----- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
**Returns:** `VisitResult`
###### visit_figcaption()
[Section titled “visit_figcaption()”](#visit_figcaption)
Visit figcaption elements `<figcaption>`.
**Signature:**
```zig
pub fn visit_figcaption(self: *const HtmlVisitor, ctx: []const u8, text: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_figcaption(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| ------ | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `text` | `\[\]const u8` | Yes | The text |
**Returns:** `VisitResult`
###### visit_figure_end()
[Section titled “visit_figure_end()”](#visit_figure_end)
Called after processing a figure `</figure>`.
**Signature:**
```zig
pub fn visit_figure_end(self: *const HtmlVisitor, ctx: []const u8, output: []const u8) VisitResult
```
**Example:**
```zig
const result = instance.visit_figure_end(.{}, "value");
```
**Parameters:**
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ---------------- |
| `ctx` | `\[\]const u8` | Yes | The node context |
| `output` | `\[\]const u8` | Yes | The output |
**Returns:** `VisitResult`
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `[]const []const []const u8` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ----- | ------- | ----------------- |
| `width` | `u32` | — | Width in pixels. |
| `height` | `u32` | — | Height in pixels. |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | --------------------------------- | ------- | ------------------------------------------------------- |
| `src` | `\[\]const u8` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `\[\]const u8?` | `null` | Alternative text from alt attribute (for accessibility) |
| `title` | `\[\]const u8?` | `null` | Title attribute (often shown as tooltip) |
| `dimensions` | `ImageDimensions?` | `null` | Image dimensions in pixels, if available. |
| `image_type` | `ImageType` | — | Image type classification |
| `attributes` | `std.StringHashMap(\[\]const u8)` | — | Additional HTML attributes |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | --------------------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `\[\]const u8` | — | The href URL value |
| `text` | `\[\]const u8` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `\[\]const u8?` | `null` | Optional title attribute (often shown as tooltip) |
| `link_type` | `LinkType` | — | Link type classification |
| `rel` | `\[\]const \[\]const u8` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `std.StringHashMap(\[\]const u8)` | — | Additional HTML attributes |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------------- | ------- | ------------------------------------------------------------- |
| `key` | `\[\]const u8` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `\[\]const u8` | — | Metadata value. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `std.StringHashMap([]const u8)`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| ----------------- | --------------- | ------- | ------------------------------------------------------- |
| `node_type` | `NodeType` | — | Coarse-grained node type classification |
| `tag_name` | `\[\]const u8` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `u64` | — | Depth in the DOM tree (0 = root) |
| `index_in_parent` | `u64` | — | Index among siblings (0-based) |
| `parent_tag` | `\[\]const u8?` | `null` | Parent element’s tag name (None if root) |
| `is_inline` | `bool` | — | Whether this element is treated as inline vs block |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------- | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `enabled` | `bool` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset.standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `remove_navigation` | `bool` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `remove_forms` | `bool` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | -------------- | ------- | ------------------------------- |
| `message` | `\[\]const u8` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------- | -------------------- | ------- | --------------------------------------------------------------- |
| `data_type` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `raw_json` | `\[\]const u8` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schema_type` | `\[\]const u8?` | `null` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | -------------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `\[\]const u8` | — | The markdown rendering of this table. |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `u32` | — | Number of rows. |
| `cols` | `u32` | — | Number of columns. |
| `cells` | `\[\]const GridCell` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `u32` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `u32` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
***
### Enums
[Section titled “Enums”](#enums)
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Value | Description |
| --------------- | ---------------------------------------------------- |
| `left_to_right` | Left-to-right text flow (default for Latin scripts) |
| `right_to_left` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `auto` | Automatic directionality detection |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `anchor` | Anchor link within same document (href starts with #) |
| `internal` | Internal link within same domain |
| `external` | External link to different domain |
| `email` | Email link (mailto:) |
| `phone` | Phone link (tel:) |
| `other` | Other protocol or unclassifiable |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `data_uri` | Data URI embedded image (base64 or other encoding) |
| `inline_svg` | Inline SVG element |
| `external` | External image URL (http/https) |
| `relative` | Relative image path |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Value | Description |
| ----------- | ---------------------------------------------------------- |
| `json_ld` | JSON-LD (JSON for Linking Data) script blocks |
| `microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Value | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Value | Description |
| ------------ | -------------------------------------------------- |
| `underlined` | Underlined style (=== for h1, — for h2). |
| `atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `atx_closed` | ATX closed style (# title #, with closing hashes). |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Value | Description |
| -------- | ----------------------------------------------------------------------------- |
| `spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `tabs` | Use tabs for indentation. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Value | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Value | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Value | Description |
| -------------- | ------------------------------------------------------------ |
| `double_equal` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `html` | Preserve as HTML (==text==). Original HTML tag. |
| `bold` | Render as bold (**text**). Uses strong emphasis. |
| `none` | Strip formatting, render as plain text. No markup. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Value | Description |
| ----------- | ---------------------------------------------------------------------- |
| `inline` | Inline links: `text`. Default. |
| `reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Value | Description |
| --------- | ----------------------------------------------------------------------------- |
| `angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Value | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `keep` | Write the `data:` URL as the destination, payload included. Default. |
| `alt_text_only` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `drop_element` | Write nothing for the element. |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Value | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `drop` | Drop the text a browser does not show at first. Default. |
| `reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `all` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Value | Description |
| ---------- | ----------------------------------------------------- |
| `markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `djot` | Djot lightweight markup language. |
| `plain` | Plain text output (no markup, visible text only). |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Value | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading` | A heading element (h1-h6). — Fields: `level`: `u8`, `text`: `[]const u8` |
| `paragraph` | A paragraph of text. — Fields: `text`: `[]const u8` |
| `list` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `bool` |
| `list_item` | A single list item. — Fields: `text`: `[]const u8` |
| `table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `image` | An image element. — Fields: `description`: `[]const u8`, `src`: `[]const u8`, `image_index`: `u32` |
| `code` | A code block or inline code. — Fields: `text`: `[]const u8`, `language`: `[]const u8` |
| `quote` | A block quote container. |
| `definition_list` | A definition list container. |
| `definition_item` | A definition list entry with term and description. — Fields: `term`: `[]const u8`, `definition`: `[]const u8` |
| `raw_block` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `[]const u8`, `content`: `[]const u8` |
| `metadata_block` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `[]const MetadataEntry` |
| `group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `[]const u8`, `heading_level`: `u8`, `heading_text`: `[]const u8` |
***
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Value | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| `bold` | Bold / strong emphasis. |
| `italic` | Italic / emphasis. |
| `underline` | Underline. |
| `strikethrough` | Strikethrough / deleted text. |
| `code` | Inline code. |
| `subscript` | Subscript text. |
| `superscript` | Superscript text. |
| `highlight` | Highlighted / marked text. |
| `link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `[]const u8`, `title`: `[]const u8` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Value | Description |
| ------------------------- | ---------------------------------------------------------------------------- |
| `image_extraction_failed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `encoding_fallback` | The input encoding was not recognized; fell back to UTF-8. |
| `truncated_input` | The input was truncated due to size limits. |
| `malformed_html` | The HTML was malformed but processing continued with best effort. |
| `sanitization_applied` | Sanitization was applied to remove potentially unsafe content. |
| `depth_limit_exceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Value | Description |
| ------------------------ | ---------------------------------------------- |
| `text` | Text node (most frequent - 100+ per document) |
| `element` | Generic element node |
| `heading` | Heading elements (h1-h6) |
| `paragraph` | Paragraph element |
| `div` | Generic div container |
| `blockquote` | Blockquote element |
| `pre` | Preformatted text block |
| `hr` | Horizontal rule |
| `list` | Ordered or unordered list (ul, ol) |
| `list_item` | List item (li) |
| `definition_list` | Definition list (dl) |
| `definition_term` | Definition term (dt) |
| `definition_description` | Definition description (dd) |
| `table` | Table element |
| `table_row` | Table row (tr) |
| `table_cell` | Table cell (td, th) |
| `table_header` | Table header cell (th) |
| `table_body` | Table body (tbody) |
| `table_head` | Table head (thead) |
| `table_foot` | Table foot (tfoot) |
| `link` | Anchor link (a) |
| `image` | Image (img) |
| `strong` | Strong/bold (strong, b) |
| `em` | Emphasis/italic (em, i) |
| `code` | Inline code (code) |
| `strikethrough` | Strikethrough (s, del, strike) |
| `underline` | Underline (u, ins) |
| `subscript` | Subscript (sub) |
| `superscript` | Superscript (sup) |
| `mark` | Mark/highlight (mark) |
| `small` | Small text (small) |
| `br` | Line break (br) |
| `span` | Span element |
| `article` | Article element |
| `section` | Section element |
| `nav` | Navigation element |
| `aside` | Aside element |
| `header` | Header element |
| `footer` | Footer element |
| `main` | Main element |
| `figure` | Figure element |
| `figcaption` | Figure caption |
| `time` | Time element |
| `details` | Details element |
| `summary` | Summary element |
| `form` | Form element |
| `input` | Input element |
| `select` | Select element |
| `option` | Option element |
| `button` | Button element |
| `textarea` | Textarea element |
| `label` | Label element |
| `fieldset` | Fieldset element |
| `legend` | Legend element |
| `audio` | Audio element |
| `video` | Video element |
| `picture` | Picture element |
| `source` | Source element |
| `iframe` | Iframe element |
| `svg` | SVG element |
| `canvas` | Canvas element |
| `ruby` | Ruby annotation |
| `rt` | Ruby text |
| `rp` | Ruby parenthesis |
| `abbr` | Abbreviation |
| `kbd` | Keyboard input |
| `samp` | Sample output |
| `var` | Variable |
| `cite` | Citation |
| `q` | Quote |
| `del` | Deleted text |
| `ins` | Inserted text |
| `data` | Data element |
| `meter` | Meter element |
| `progress` | Progress element |
| `output` | Output element |
| `template` | Template element |
| `slot` | Slot element |
| `html` | HTML root element |
| `head` | Head element |
| `body` | Body element |
| `title` | Title element |
| `meta` | Meta element |
| `link_tag` | Link element (not anchor) |
| `style` | Style element |
| `script` | Script element |
| `base` | Base element |
| `custom` | Custom element (web components) or unknown tag |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Value | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `continue` | Continue with default conversion behavior |
| `custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `[]const u8` |
| `skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `preserve_html` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `[]const u8` |
***
### Errors
[Section titled “Errors”](#errors)
#### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parse_error` | HTML parsing error |
| `sanitization_error` | HTML sanitization error |
| `config_error` | Invalid configuration |
| `io_error` | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `panic` | Internal error caught during conversion |
| `invalid_input` | Invalid input data |
| `input_too_large` | Input exceeds the configured byte limit. |
| `other` | Generic conversion error |
***
# CLI Reference
## CLI Reference
[Section titled “CLI Reference”](#cli-reference)
## `html-to-markdown`
[Section titled “html-to-markdown”](#html-to-markdown)
Convert HTML to Markdown
### Arguments
[Section titled “Arguments”](#arguments)
| Name | Flags | Type | Default | Description |
| ------- | ----- | ---------------- | ------- | ------------------------------------------- |
| `input` | | `Option<String>` | | Input HTML file (use "-" or omit for stdin) |
### Options
[Section titled “Options”](#options)
| Name | Flags | Type | Default | Description |
| ------------------------- | --------------------------- | -------------------------------- | ------- | -------------------------------------------------------------------------------- |
| `url` | `--url` | `Option<String>` | | Fetch HTML from a URL (alternative to file/stdin) |
| `user_agent` | `--user-agent` | `Option<String>` | | User-Agent header when fetching via –url (default mimics a real browser) |
| `output` | `-o`, `--output` | `Option<PathBuf>` | | Output file (default: stdout) |
| `generate_completion` | `--generate-completion` | `Option<Shell>` | | Generate shell completion script |
| `generate_man` | `--generate-man` | `bool` | | Generate man page |
| `heading_style` | `--heading-style` | `Option<CliHeadingStyle>` | | Heading style |
| `list_indent_type` | `--list-indent-type` | `Option<CliListIndentType>` | | List indentation type |
| `list_indent_width` | `--list-indent-width` | `Option<u8>` | | Spaces per list indent level |
| `bullets` | `-b`, `--bullets` | `Option<String>` | | Bullet characters for unordered lists |
| `strong_em_symbol` | `--strong-em-symbol` | `Option<char>` | | Symbol for bold and italic |
| `escape_asterisks` | `--escape-asterisks` | `bool` | | Escape asterisk (\*) characters |
| `escape_underscores` | `--escape-underscores` | `bool` | | Escape underscore (\_) characters |
| `escape_misc` | `--escape-misc` | `bool` | | Escape misc Markdown characters |
| `escape_ascii` | `--escape-ascii` | `bool` | | Escape all ASCII punctuation |
| `sub_symbol` | `--sub-symbol` | `Option<String>` | | Symbol to wrap subscript text |
| `sup_symbol` | `--sup-symbol` | `Option<String>` | | Symbol to wrap superscript text |
| `newline_style` | `--newline-style` | `Option<CliNewlineStyle>` | | Line break style |
| `code_block_style` | `--code-block-style` | `Option<CliCodeBlockStyle>` | | Code block style |
| `code_language` | `-l`, `--code-language` | `Option<String>` | | Default language for code blocks |
| `no_autolinks` | `--no-autolinks` | `bool` | | Disable autolink conversion |
| `no_expand_abbreviations` | `--no-expand-abbreviations` | `bool` | | Disable abbreviation expansion |
| `no_blockquote_citations` | `--no-blockquote-citations` | `bool` | | Disable blockquote citations |
| `link_style` | `--link-style` | `Option<CliLinkStyle>` | | Link rendering style |
| `default_title` | `--default-title` | `bool` | | Add default title to links |
| `url_escape_style` | `--url-escape-style` | `Option<CliUrlEscapeStyle>` | | URL escaping style for link and image destinations |
| `keep_inline_images_in` | `--keep-inline-images-in` | `Option<Vec<String>>` | | Keep inline images in specific elements |
| `max_image_size` | `--max-image-size` | `Option<u64>` | | Maximum decoded image size in bytes |
| `capture_svg` | `--capture-svg` | `bool` | | Capture inline `<svg>` elements as images |
| `no_infer_dimensions` | `--no-infer-dimensions` | `bool` | | Disable image dimension inference |
| `br_in_tables` | `--br-in-tables` | `bool` | | Use in table cells |
| `compact_tables` | `--compact-tables` | `bool` | | Emit compact (unpadded) GFM tables |
| `highlight_style` | `--highlight-style` | `Option<CliHighlightStyle>` | | Style for `<mark>` elements |
| `extract_metadata` | `--extract-metadata` | `bool` | | Extract metadata from HTML |
| `json` | `--json` | `bool` | | Output full `ConversionResult` as JSON instead of markdown text |
| `include_structure` | `--include-structure` | `bool` | | Include structured document tree in output |
| `extract_inline_images` | `--extract-inline-images` | `bool` | | Extract inline images from data URIs and SVGs |
| `show_warnings` | `--show-warnings` | `bool` | | Emit one WARN-level tracing event per conversion warning |
| `no_content` | `--no-content` | `bool` | | Null out the “content” field in JSON output |
| `whitespace_mode` | `--whitespace-mode` | `Option<CliWhitespaceMode>` | | Whitespace handling mode |
| `strip_newlines` | `--strip-newlines` | `bool` | | Strip newlines from input |
| `wrap` | `-w`, `--wrap` | `bool` | | Enable text wrapping |
| `wrap_width` | `--wrap-width` | `Option<u16>` | | Wrap width in columns |
| `convert_as_inline` | `--convert-as-inline` | `bool` | | Treat block elements as inline |
| `strip_tags` | `--strip-tags` | `Option<Vec<String>>` | | HTML tags to strip |
| `preserve_tags` | `--preserve-tags` | `Option<Vec<String>>` | | HTML tags to preserve verbatim |
| `skip_images` | `--skip-images` | `bool` | | Skip image elements |
| `inline_data_media` | `--inline-data-media` | `Option<CliInlineDataMedia>` | | What to write for an image, media element, or link, whose address is a data: URL |
| `hidden_content` | `--hidden-content` | `Option<CliHiddenContent>` | | Which text that a browser does not show at first to keep |
| `exclude_selectors` | `--exclude-selectors` | `Option<Vec<String>>` | | CSS selectors for elements to exclude entirely |
| `max_depth` | `--max-depth` | `Option<usize>` | | Maximum DOM traversal depth |
| `preprocess` | `-p`, `--preprocess` | `bool` | | Enable HTML preprocessing |
| `preset` | `--preset` | `Option<CliPreprocessingPreset>` | | Preprocessing aggressiveness preset |
| `keep_navigation` | `--keep-navigation` | `bool` | | Keep navigation elements |
| `keep_forms` | `--keep-forms` | `bool` | | Keep form elements |
| `tier_strategy` | `--tier-strategy` | `Option<CliTierStrategy>` | | Conversion tier strategy |
| `encoding` | `-e`, `--encoding` | `String` | `utf-8` | Input character encoding |
| `debug` | `--debug` | `bool` | | Enable debug mode |
| `output_format` | `-f`, `--output-format` | `Option<CliOutputFormat>` | | Output format (markdown or djot) |
# Configuration Reference
## Configuration Reference
[Section titled “Configuration Reference”](#configuration-reference)
This page documents all configuration types and their defaults across all languages.
### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| ---------------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `str \| None` | `None` | Document title from `<title>` tag |
| `description` | `str \| None` | `None` | Document description from `<meta name="description">` tag |
| `keywords` | `list\[str\]` | `[]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `str \| None` | `None` | Document author from `<meta name="author">` tag |
| `canonical_url` | `str \| None` | `None` | Canonical URL from `<link rel="canonical">` tag |
| `base_href` | `str \| None` | `None` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `str \| None` | `None` | Document language from `lang` attribute |
| `text_direction` | `TextDirection \| None` | `None` | Document text direction from `dir` attribute |
| `open_graph` | `dict\[str, str\]` | `{}` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitter_card` | `dict\[str, str\]` | `{}` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `meta_tags` | `dict\[str, str\]` | `{}` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ----------------- | ------------------------ | ------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `list\[HeaderMetadata\]` | `[]` | Extracted header elements with hierarchy |
| `links` | `list\[LinkMetadata\]` | `[]` | Extracted hyperlinks with type classification |
| `images` | `list\[ImageMetadata\]` | `[]` | Extracted images with source and dimensions |
| `structured_data` | `list\[StructuredData\]` | `[]` | Extracted structured data blocks |
***
### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ------------------------------ | ----------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading_style` | `HeadingStyle` | `HeadingStyle.ATX` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `list_indent_type` | `ListIndentType` | `ListIndentType.SPACES` | How to indent nested list items (spaces or tab). |
| `list_indent_width` | `int` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `str` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strong_em_symbol` | `str` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escape_asterisks` | `bool` | `False` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escape_underscores` | `bool` | `False` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escape_misc` | `bool` | `False` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escape_ascii` | `bool` | `False` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `code_language` | `str` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `bool` | `True` | Automatically convert bare URLs into Markdown autolinks. |
| `expand_abbreviations` | `bool` | `True` | Append the title of an `<abbr>` in parentheses (default `True`). |
| `include_blockquote_citations` | `bool` | `True` | Append the `cite` URL after a blockquote (default `True`). |
| `default_title` | `bool` | `False` | Emit a default title when no `<title>` tag is present. |
| `br_in_tables` | `bool` | `False` | Render `<br>` elements inside table cells as literal line breaks. |
| `compact_tables` | `bool` | `False` | Emit tables without column padding (compact GFM format). When `True`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `False` (aligned padding preserved). |
| `highlight_style` | `HighlightStyle` | `HighlightStyle.DOUBLE_EQUAL` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extract_metadata` | `bool` | `True` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `True`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespace_mode` | `WhitespaceMode` | `WhitespaceMode.NORMALIZED` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode.Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode.Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `strip_newlines` | `bool` | `False` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `bool` | `False` | Wrap long lines at `wrap_width` characters. |
| `wrap_width` | `int` | `80` | Maximum output line width in characters when `wrap` is `True` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `False`. |
| `convert_as_inline` | `bool` | `False` | Treat the entire document as inline content (no block-level wrappers). |
| `sub_symbol` | `str` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `sup_symbol` | `str` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newline_style` | `NewlineStyle` | `NewlineStyle.SPACES` | How to encode hard line breaks (`<br>`) in Markdown. |
| `code_block_style` | `CodeBlockStyle` | `CodeBlockStyle.BACKTICKS` | Style used for fenced code blocks (backticks or tilde). |
| `keep_inline_images_in` | `list\[str\]` | `[]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to the standard preprocessing options, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions.builder`) to opt in or out of specific passes. |
| `encoding` | `str` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `bool` | `False` | Emit debug information during conversion. |
| `strip_tags` | `list\[str\]` | `[]` | HTML tag names whose content is stripped from the output entirely. |
| `preserve_tags` | `list\[str\]` | `[]` | HTML tag names that are preserved verbatim in the output. |
| `skip_images` | `bool` | `False` | Skip conversion of `<img>` elements (omit images from output). |
| `inline_data_media` | `InlineDataMedia` | `InlineDataMedia.KEEP` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia.Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hidden_content` | `HiddenContent` | `HiddenContent.DROP` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent.Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent.Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent.All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `url_escape_style` | `UrlEscapeStyle` | `UrlEscapeStyle.ANGLE` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle.Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle.Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `link_style` | `LinkStyle` | `LinkStyle.INLINE` | Link rendering style (inline or reference). |
| `output_format` | `OutputFormat` | `OutputFormat.MARKDOWN` | Target output format (Markdown, plain text, etc.). |
| `include_document_structure` | `bool` | `False` | Include structured document tree in result. |
| `extract_images` | `bool` | `False` | Extract inline images from data URIs and SVGs. |
| `max_image_size` | `int` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `max_input_size` | `int \| None` | `None` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `None`. Set `Some(bytes)` to choose another limit or `None` to disable it. |
| `capture_svg` | `bool` | `False` | Capture SVG elements as images. |
| `infer_dimensions` | `bool` | `True` | Infer image dimensions from data. |
| `max_depth` | `int \| None` | `None` | Maximum DOM traversal depth. `None` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `exclude_selectors` | `list\[str\]` | `[]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `[".cookie-banner", "#ad-container", "[role='complementary']"]` |
| `tier_strategy` | `TierStrategy` | `TierStrategy.AUTO` | Which conversion tier to use. - `TierStrategy.Auto` (default) — automatically choose the best path. - `TierStrategy.Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy.Tier1` — always attempt Tier-1 (testkit only). |
| `base_url` | `str \| None` | `None` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `None` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `VisitorHandle \| None` | `None` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------- | --------------------- | ------------------------------ | -------------------------------------------------------------- |
| `enabled` | `bool` | `True` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset.STANDARD` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `remove_navigation` | `bool` | `True` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `remove_forms` | `bool` | `True` | Remove form elements (forms, inputs, buttons, etc.) |
***
### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `str \| None` | `None` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `DocumentStructure \| None` | `None` | Structured document tree with semantic elements. Populated when the `include_document_structure` option is `True`. `None` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in the result’s `tables` field. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `list\[TableData\]` | `[]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self.document`, so it is populated only when the `include_document_structure` option is `True`. With the default options this is an empty list even for input that contains tables — the tables still appear in `Self.content` as rendered Markdown. |
| `warnings` | `list\[ProcessingWarning\]` | `[]` | Non-fatal processing warnings. |
***
### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `int` | — | Number of rows. |
| `cols` | `int` | — | Number of columns. |
| `cells` | `list\[GridCell\]` | `[]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this list is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty list. |
***
### Enums
[Section titled “Enums”](#enums)
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Variant | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Variant | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Variant | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Variant | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Variant | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Variant | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Variant | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Variant | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Variant | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Variant | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Variant | Wire value | Description |
| ------------- | ---------- | ---------------------------------------------------- |
| `LeftToRight` | `ltr` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | `rtl` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | `auto` | Automatic directionality detection |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Variant | Wire value | Description |
| ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | `auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | `tier2` | Always use the Tier-2 (`tl.parse` + walk) path, skipping Tier-1. |
| `Tier1` | `tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Variant | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Variant | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
# Error Reference
## Error Reference
[Section titled “Error Reference”](#error-reference)
All error types thrown by the library across all languages.
### ConversionError
[Section titled “ConversionError”](#conversionerror)
Errors that can occur during HTML to Markdown conversion.
| Variant | Message | Description |
| ------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ParseError` | HTML parsing error: {0} | HTML parsing error |
| `SanitizationError` | Sanitization error: {0} | HTML sanitization error |
| `ConfigError` | Invalid configuration: {0} | Invalid configuration |
| `IoError` | I/O error: {0} | I/O error — stores the error message string so the variant is FFI-safe. Use `ConversionError.from(io_error)` to convert from an operating-system I/O error. |
| `Panic` | Internal panic: {0} | Internal error caught during conversion |
| `InvalidInput` | Invalid input: {0} | Invalid input data |
| `InputTooLarge` | Input size {observed_size} bytes exceeds the configured maximum of {max_size} bytes | Input exceeds the configured byte limit. |
| `Other` | Conversion error: {0} | Generic conversion error |
***
# MCP Reference
## MCP Reference
[Section titled “MCP Reference”](#mcp-reference)
### Tools
[Section titled “Tools”](#tools)
| Name | Title | Parameters | Description |
| ------------------ | --------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `convert_html` | Convert HTML | `Parameters<super::params::ConvertHtmlParams>` | Convert HTML to Markdown (or Djot/plain via config.output_format). Pass json:true for the full ConversionResult (content, tables, document structure, metadata, warnings). Pass config to control heading style, list formatting, escaping, preprocessing, image extraction, and more — see the input schema for every option. |
| `extract_metadata` | Extract HTML Metadata | `Parameters<super::params::ExtractMetadataParams>` | Extract structured metadata from HTML as JSON: document title/description/keywords/author, Open Graph and Twitter Card tags, JSON-LD and microdata, plus header, link, and image inventories. Convenience over convert_html for metadata-only use. |
# Types Reference
## Types Reference
[Section titled “Types Reference”](#types-reference)
All types defined by the library, grouped by category. Types are shown using Rust as the canonical representation.
### Result Types
[Section titled “Result Types”](#result-types)
#### ConversionResult
[Section titled “ConversionResult”](#conversionresult)
The primary result of HTML conversion and extraction.
Contains the converted text output, optional structured document tree, metadata, extracted tables, images, and processing warnings.
| Field | Type | Default | Description |
| ---------- | --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `content` | `Option<String>` | `Default::default()` | Converted text output in the selected format: Markdown, Djot, or plain text. |
| `document` | `Option<DocumentStructure>` | `Default::default()` | Structured document tree with semantic elements. Populated when `ConversionOptions::include_document_structure` is `true`. `None` otherwise (the default), which avoids the overhead of building the tree. When present, the tree mirrors the converted document: headings open `Group` sections, paragraphs and list items carry inline `TextAnnotation`s, and tables reference the same `TableGrid` data exposed in `Self::tables`. Note: this field is independent of the `metadata` feature flag. Document structure collection is always available at runtime; it is gated only by the runtime option, not by a compile-time feature. |
| `metadata` | `HtmlMetadata` | — | Extracted HTML metadata (title, OG, links, images, structured data). |
| `tables` | `Vec<TableData>` | `vec![]` | Extracted tables with structured cell data and markdown representation. Table data is collected by the same pass that builds `Self::document`, so it is populated only when `ConversionOptions::include_document_structure` is `true`. With the default options this is an empty vec even for input that contains tables — the tables still appear in `Self::content` as rendered Markdown. |
| `warnings` | `Vec<ProcessingWarning>` | `vec![]` | Non-fatal processing warnings. |
***
### Configuration Types
[Section titled “Configuration Types”](#configuration-types)
See [Configuration Reference](configuration.md) for detailed defaults and language-specific representations.
#### ConversionOptions
[Section titled “ConversionOptions”](#conversionoptions)
Main conversion options for HTML to Markdown conversion.
Use `ConversionOptions.builder()` to construct, or `the default constructor` for defaults.
| Field | Type | Default | Description |
| ------------------------------ | ----------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading_style` | `HeadingStyle` | `HeadingStyle::Atx` | Heading style to use in Markdown output (ATX `#` or Setext underline). |
| `list_indent_type` | `ListIndentType` | `ListIndentType::Spaces` | How to indent nested list items (spaces or tab). |
| `list_indent_width` | `usize` | `2` | Number of spaces (or tabs) to use for each level of list indentation. |
| `bullets` | `String` | `"-*+"` | Bullet character(s) to use for unordered list items (e.g. `"-"`, `"*"`). |
| `strong_em_symbol` | `String` | `"*"` | Character used for bold/italic emphasis markers (`*` or `_`). |
| `escape_asterisks` | `bool` | `false` | Escape `*` characters in plain text to avoid unintended bold/italic. |
| `escape_underscores` | `bool` | `false` | Escape `_` characters in plain text to avoid unintended bold/italic. |
| `escape_misc` | `bool` | `false` | Escape miscellaneous Markdown metacharacters (`[]()#` etc.) in plain text. |
| `escape_ascii` | `bool` | `false` | Escape ASCII characters that have special meaning in certain Markdown dialects. |
| `code_language` | `String` | `""` | Default language annotation for fenced code blocks that have no language hint. |
| `autolinks` | `bool` | `true` | Automatically convert bare URLs into Markdown autolinks. |
| `expand_abbreviations` | `bool` | `true` | Append the title of an `<abbr>` in parentheses (default `true`). |
| `include_blockquote_citations` | `bool` | `true` | Append the `cite` URL after a blockquote (default `true`). |
| `default_title` | `bool` | `false` | Emit a default title when no `<title>` tag is present. |
| `br_in_tables` | `bool` | `false` | Render `<br>` elements inside table cells as literal line breaks. |
| `compact_tables` | `bool` | `false` | Emit tables without column padding (compact GFM format). When `true`, column widths are not computed and cells are emitted with no trailing spaces. Separator rows use exactly `---` per column. Produces token-efficient output suitable for RAG / LLM contexts. Default `false` (aligned padding preserved). |
| `highlight_style` | `HighlightStyle` | `HighlightStyle::DoubleEqual` | Style used for `<mark>` / highlighted text (e.g. `==text==`). |
| `extract_metadata` | `bool` | `true` | Populate `result.metadata` with `<head>` / `<meta>` extraction (title, description, Open Graph, Twitter Card, JSON-LD, …). Default `true`. Disabling skips the metadata pass only — table extraction into `result.tables` runs unconditionally. |
| `whitespace_mode` | `WhitespaceMode` | `WhitespaceMode::Normalized` | Controls how whitespace sequences are normalised in the converted output. - `WhitespaceMode::Normalized` (default) — collapses consecutive whitespace characters (spaces, tabs, newlines) to a single space, matching browser rendering behaviour. - `WhitespaceMode::Strict` — preserves all whitespace exactly as it appears in the source HTML, including runs of spaces and embedded newlines. Choose `Strict` only when the source HTML uses deliberate whitespace (e.g. pre-formatted content outside `<pre>` tags). For most documents `Normalized` produces cleaner output. |
| `strip_newlines` | `bool` | `false` | Strip all newlines from the output, producing a single-line result. |
| `wrap` | `bool` | `false` | Wrap long lines at `wrap_width` characters. |
| `wrap_width` | `usize` | `80` | Maximum output line width in characters when `wrap` is `true` (default `80`). Lines are broken at word boundaries so that no line exceeds this length. A value of `0` is treated as “no limit” — equivalent to leaving `wrap` disabled. Has no effect when `wrap` is `false`. |
| `convert_as_inline` | `bool` | `false` | Treat the entire document as inline content (no block-level wrappers). |
| `sub_symbol` | `String` | `""` | Markdown notation for subscript text (e.g. `"~"`). |
| `sup_symbol` | `String` | `""` | Markdown notation for superscript text (e.g. `"^"`). |
| `newline_style` | `NewlineStyle` | `NewlineStyle::Spaces` | How to encode hard line breaks (`<br>`) in Markdown. |
| `code_block_style` | `CodeBlockStyle` | `CodeBlockStyle::Backticks` | Style used for fenced code blocks (backticks or tilde). |
| `keep_inline_images_in` | `Vec<String>` | `vec![]` | HTML tag names whose `<img>` children are kept inline instead of block. |
| `preprocessing` | `PreprocessingOptions` | — | Options for the HTML pre-processing pass applied before conversion begins. Pre-processing runs before the HTML is handed to the converter and can perform operations such as unwrapping redundant wrapper elements, removing tracking pixels, and normalising vendor-specific markup. See `PreprocessingOptions` for the full set of knobs. Defaults to `PreprocessingOptions::default()`, which enables the standard cleaning passes. Set individual fields on `PreprocessingOptions` (or construct via `ConversionOptions::builder`) to opt in or out of specific passes. |
| `encoding` | `String` | `"utf-8"` | Expected character encoding of the input HTML (default `"utf-8"`). |
| `debug` | `bool` | `false` | Emit debug information during conversion. |
| `strip_tags` | `Vec<String>` | `vec![]` | HTML tag names whose content is stripped from the output entirely. |
| `preserve_tags` | `Vec<String>` | `vec![]` | HTML tag names that are preserved verbatim in the output. |
| `skip_images` | `bool` | `false` | Skip conversion of `<img>` elements (omit images from output). |
| `inline_data_media` | `InlineDataMedia` | `InlineDataMedia::Keep` | What the output shows for an image or embedded media element whose address is an inline `data:` URL: the URL with its payload (`InlineDataMedia::Keep`, the default), the alt text alone, or nothing. See `InlineDataMedia` for the elements it covers. |
| `hidden_content` | `HiddenContent` | `HiddenContent::Drop` | Which text that a browser does not show at first the output holds: none of it (`HiddenContent::Drop`, the default), the text a reader can get to in the page, such as an inactive tab panel (`HiddenContent::Reachable`), or that text and the content of `<template>` and `<noscript>` (`HiddenContent::All`). No choice writes a script or a style sheet as text. See `HiddenContent` for each kind of hidden markup. |
| `url_escape_style` | `UrlEscapeStyle` | `UrlEscapeStyle::Angle` | URL encoding strategy for link and image destinations. Controls how special characters in URL destinations are escaped: - `UrlEscapeStyle::Angle` (default) — wraps the destination in angle brackets when it contains spaces or newlines. Some parsers misinterpret `>` inside such a destination. - `UrlEscapeStyle::Percent` — percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination that all Markdown parsers handle correctly even when the URL contains `<`, `>`, spaces, or parentheses. |
| `link_style` | `LinkStyle` | `LinkStyle::Inline` | Link rendering style (inline or reference). |
| `output_format` | `OutputFormat` | `OutputFormat::Markdown` | Target output format (Markdown, plain text, etc.). |
| `include_document_structure` | `bool` | `false` | Include structured document tree in result. |
| `extract_images` | `bool` | `false` | Extract inline images from data URIs and SVGs. |
| `max_image_size` | `u64` | `5242880` | Maximum decoded image size in bytes (default 5MB). |
| `max_input_size` | `Option<u64>` | `None` | Maximum accepted HTML input size in bytes. WebAssembly builds default to `DEFAULT_WASM_MAX_INPUT_SIZE` (2 MiB) to avoid an uncatchable stack-exhaustion trap on unusually large DOMs. Native builds default to `None`. Set `Some(bytes)` to choose another limit or `None` to disable it. |
| `capture_svg` | `bool` | `false` | Capture SVG elements as images. |
| `infer_dimensions` | `bool` | `true` | Infer image dimensions from data. |
| `max_depth` | `Option<usize>` | `None` | Maximum DOM traversal depth. `None` uses the library’s internal native-stack safety limit. Explicit values above that safety limit are clamped to prevent process-aborting stack overflows on pathologically deep DOM trees. |
| `exclude_selectors` | `Vec<String>` | `vec![]` | CSS selectors for elements to exclude entirely (element + all content). Unlike `strip_tags` (which removes the tag wrapper but keeps children), excluded elements and all their descendants are dropped from the output. A selector matches an element by its own properties: a tag name (`nav`), `.class`, `#id`, an attribute (`[hidden]`, `[role=banner]`, and the `~=`, `^=`, `$=` and `*=` forms), `*`, and these joined with no space (`div.note`, `a[href$="share"]`). One entry can hold a comma-separated list of such selectors (`nav, footer`). Write a tag name in lower case. A selector with a combinator (`.menu a`, `div > p`, `h2 + p`, `h2 ~ p`) or a pseudo-class (`li:first-child`) matches nothing, and the conversion reports no error. In a comma-separated list, such a member can stop the other members of the list too: give each selector as an entry of its own. Invalid selectors are silently skipped at conversion time. Example: `vec![".cookie-banner".into(), "#ad-container".into(), "[role='complementary']".into()]` |
| `tier_strategy` | `TierStrategy` | `TierStrategy::Auto` | Which conversion tier to use. - `TierStrategy::Auto` (default) — automatically choose the best path. - `TierStrategy::Tier2` — always use the Tier-2 DOM-walk path. - `TierStrategy::Tier1` — always attempt Tier-1 (testkit only). |
| `base_url` | `Option<String>` | `None` | Base URL to resolve relative `href`/`src` destinations against. When set, every relative link and image/media destination (`a href`, `img src` and its lazy-load fallbacks, `srcset`, `graphic` `url`/`href`/`xlink:href`/`src`, `iframe`/`audio`/`video`/`source` `src`) is resolved to an absolute URL before being written to the Markdown output, so the result is followable without the reader knowing where the source HTML came from. A `<base href>` in the document, if present, is honored the way a browser honors it: it is itself resolved against `base_url`, and that combined result becomes the effective base every other relative reference resolves against. Non-hierarchical schemes (`mailto:`, `tel:`, `javascript:`, `data:`) and already-absolute URLs are left unchanged. An unset (default) or unparseable `base_url`, and a relative reference that fails to resolve, leave the original attribute text unchanged – this option never panics and never corrupts a destination it cannot confidently resolve. Default `None` — no resolution, output byte-identical to versions before this option existed. |
| `visitor` | `Option<VisitorHandle>` | `None` | Optional visitor for custom traversal logic. When set, the visitor’s callbacks are invoked for matching HTML elements during conversion, allowing custom output, skipping, or HTML preservation. See `HtmlVisitor`. |
***
#### PreprocessingOptions
[Section titled “PreprocessingOptions”](#preprocessingoptions)
HTML preprocessing options for document cleanup before conversion.
| Field | Type | Default | Description |
| ------------------- | --------------------- | ------------------------------- | -------------------------------------------------------------- |
| `enabled` | `bool` | `true` | Enable HTML preprocessing globally |
| `preset` | `PreprocessingPreset` | `PreprocessingPreset::Standard` | Preprocessing preset level (Minimal, Standard, Aggressive) |
| `remove_navigation` | `bool` | `true` | Remove navigation elements (nav, breadcrumbs, menus, sidebars) |
| `remove_forms` | `bool` | `true` | Remove form elements (forms, inputs, buttons, etc.) |
***
#### TableGrid
[Section titled “TableGrid”](#tablegrid)
A structured table grid with cell-level data including spans.
| Field | Type | Default | Description |
| ------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | `u32` | — | Number of rows. |
| `cols` | `u32` | — | Number of columns. |
| `cells` | `Vec<GridCell>` | `vec![]` | All cells in the table as a flat, sparse list. The list is ordered by `(row, col)` but is **not** a dense `rows × cols` matrix: cells that are covered by a spanning cell (via `row_span > 1` or `col_span > 1`) do not appear in the list. Only the top-left “origin” cell of a span is present, with its `row_span` and `col_span` fields set accordingly. To reconstruct the full visual grid, iterate over all cells and mark the rectangular region `[row .. row+row_span, col .. col+col_span]` as occupied by that cell. Any `(row, col)` position that is not the origin of any cell is covered by a span from an earlier cell. The length of this vec is `≤ rows * cols`. An empty table (`rows == 0 \|\| cols == 0`) produces an empty vec. |
***
### Metadata Types
[Section titled “Metadata Types”](#metadata-types)
#### DocumentMetadata
[Section titled “DocumentMetadata”](#documentmetadata)
Document-level metadata extracted from `<head>` and top-level elements.
Contains all metadata typically used by search engines, social media platforms, and browsers for document indexing and presentation.
| Field | Type | Default | Description |
| ---------------- | ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `title` | `Option<String>` | `Default::default()` | Document title from `<title>` tag |
| `description` | `Option<String>` | `Default::default()` | Document description from `<meta name="description">` tag |
| `keywords` | `Vec<String>` | `vec![]` | Document keywords from `<meta name="keywords">` tag, split on commas |
| `author` | `Option<String>` | `Default::default()` | Document author from `<meta name="author">` tag |
| `canonical_url` | `Option<String>` | `Default::default()` | Canonical URL from `<link rel="canonical">` tag |
| `base_href` | `Option<String>` | `Default::default()` | Base URL from `<base href="">` tag for resolving relative URLs |
| `language` | `Option<String>` | `Default::default()` | Document language from `lang` attribute |
| `text_direction` | `Option<TextDirection>` | `Default::default()` | Document text direction from `dir` attribute |
| `open_graph` | `HashMap<String, String>` | `HashMap::new()` | Open Graph metadata (og:\* properties) for social media Keys like “title”, “description”, “image”, “url”, etc. |
| `twitter_card` | `HashMap<String, String>` | `HashMap::new()` | Twitter Card metadata (twitter:\* properties) Keys like “card”, “site”, “creator”, “title”, “description”, “image”, etc. |
| `meta_tags` | `HashMap<String, String>` | `HashMap::new()` | Additional meta tags not covered by specific fields Keys are meta name/property attributes, values are content |
***
#### HeaderMetadata
[Section titled “HeaderMetadata”](#headermetadata)
Header element metadata with hierarchy tracking.
Captures heading elements (h1-h6) with their text content, identifiers, and position in the document structure.
| Field | Type | Default | Description |
| ------------- | ---------------- | ------- | ----------------------------------------- |
| `level` | `u8` | — | Header level: 1 (h1) through 6 (h6) |
| `text` | `String` | — | Normalized text content of the header |
| `id` | `Option<String>` | `None` | HTML id attribute if present |
| `depth` | `usize` | — | Document tree depth at the header element |
| `html_offset` | `usize` | — | Byte offset in original HTML document |
***
#### LinkMetadata
[Section titled “LinkMetadata”](#linkmetadata)
Hyperlink metadata with categorization and attributes.
Represents `<a>` elements with parsed href values, text content, and link type classification.
| Field | Type | Default | Description |
| ------------ | ------------------------- | ------- | ------------------------------------------------------------------- |
| `href` | `String` | — | The href URL value |
| `text` | `String` | — | Link text content (normalized, concatenated if mixed with elements) |
| `title` | `Option<String>` | `None` | Optional title attribute (often shown as tooltip) |
| `link_type` | `LinkType` | — | Link type classification |
| `rel` | `Vec<String>` | — | Rel attribute values (e.g., “nofollow”, “stylesheet”, “canonical”) |
| `attributes` | `HashMap<String, String>` | — | Additional HTML attributes |
***
#### ImageMetadata
[Section titled “ImageMetadata”](#imagemetadata)
Image metadata with source and dimensions.
Captures `<img>` elements and inline `<svg>` elements with metadata for image analysis and optimization.
| Field | Type | Default | Description |
| ------------ | ------------------------- | ------- | ------------------------------------------------------- |
| `src` | `String` | — | Image source (URL, data URI, or SVG content identifier) |
| `alt` | `Option<String>` | `None` | Alternative text from alt attribute (for accessibility) |
| `title` | `Option<String>` | `None` | Title attribute (often shown as tooltip) |
| `dimensions` | `Option<ImageDimensions>` | `None` | Image dimensions in pixels, if available. |
| `image_type` | `ImageType` | — | Image type classification |
| `attributes` | `HashMap<String, String>` | — | Additional HTML attributes |
***
#### HtmlMetadata
[Section titled “HtmlMetadata”](#htmlmetadata)
Comprehensive metadata extraction result from HTML document.
Contains all extracted metadata types in a single structure, suitable for serialization and transmission across language boundaries.
| Field | Type | Default | Description |
| ----------------- | --------------------- | -------- | ------------------------------------------------------------- |
| `document` | `DocumentMetadata` | — | Document-level metadata (title, description, canonical, etc.) |
| `headers` | `Vec<HeaderMetadata>` | `vec![]` | Extracted header elements with hierarchy |
| `links` | `Vec<LinkMetadata>` | `vec![]` | Extracted hyperlinks with type classification |
| `images` | `Vec<ImageMetadata>` | `vec![]` | Extracted images with source and dimensions |
| `structured_data` | `Vec<StructuredData>` | `vec![]` | Extracted structured data blocks |
***
#### MetadataEntry
[Section titled “MetadataEntry”](#metadataentry)
A single key-value metadata entry from `<head>` meta tags.
Binding-safe replacement for `(String, String)` tuples used in `NodeContent.MetadataBlock`. Tuple pairs cannot be represented across language boundaries without lossy degradation.
| Field | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------------------- |
| `key` | `String` | — | Metadata key (e.g. `"title"`, `"description"`, `"og:title"`). |
| `value` | `String` | — | Metadata value. |
***
### Structured Data Types
[Section titled “Structured Data Types”](#structured-data-types)
#### DocumentNode
[Section titled “DocumentNode”](#documentnode)
A single node in the document tree.
| Field | Type | Default | Description |
| ------------- | ------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `String` | — | Deterministic node identifier. |
| `content` | `NodeContent` | — | The semantic content of this node. |
| `parent` | `Option<u32>` | `None` | Index of the parent node (None for root nodes). |
| `children` | `Vec<u32>` | `/* serde(default) */` | Indices of child nodes in reading order. |
| `annotations` | `Vec<TextAnnotation>` | `/* serde(default) */` | Inline formatting annotations (bold, italic, links, etc.) with byte offsets into the text. |
| `attributes` | `HashMap<String, String>` | `None` | Format-specific attributes preserved from the source HTML element. Keys are lowercased attribute names as they appear in the HTML (e.g. `"class"`, `"id"`, `"data-foo"`). Values are the raw attribute strings, copied verbatim from the source — no HTML entity decoding is applied here. The map is `None` when no attributes are present (omitted entirely in serialized output). Not every HTML attribute is preserved: only attributes that carry semantic or structural significance for the node type are collected. For example, heading nodes capture the `"id"` attribute for anchor linking; other element-level attributes may be silently dropped. |
***
#### GridCell
[Section titled “GridCell”](#gridcell)
A single cell in a table grid.
| Field | Type | Default | Description |
| ----------- | -------- | ---------------------- | ---------------------------------------------- |
| `content` | `String` | — | The text content of the cell. |
| `row` | `u32` | — | 0-indexed row position. |
| `col` | `u32` | — | 0-indexed column position. |
| `row_span` | `u32` | `1` | Number of rows this cell spans (default 1). |
| `col_span` | `u32` | `1` | Number of columns this cell spans (default 1). |
| `is_header` | `bool` | `/* serde(default) */` | Whether this is a header cell (`<th>`). |
***
#### TableData
[Section titled “TableData”](#tabledata)
A top-level extracted table with both structured data and markdown representation.
| Field | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------- |
| `grid` | `TableGrid` | — | The structured table grid. |
| `markdown` | `String` | — | The markdown rendering of this table. |
***
#### NodeContext
[Section titled “NodeContext”](#nodecontext)
Context information passed to all visitor methods.
Provides comprehensive metadata about the current node being visited, including its type, tag name, position in the DOM tree, and parent context.
##### Attributes
[Section titled “Attributes”](#attributes)
Access attributes via `NodeContext.attributes`, which returns `dict[str, str]`. When the context was built with lazy attribute extraction (the hot path inside the converter), the map is only materialized on the first call — if the visitor never reads attributes, the allocation is skipped.
##### Lifetimes
[Section titled “Lifetimes”](#lifetimes)
String fields use `Cow<'_, str>` so the converter can pass slices directly out of the parsed DOM without allocating. Visitor implementations that need to outlive the callback should call `NodeContext.into_owned`.
| Field | Type | Default | Description |
| ----------------- | ---------------- | ------- | ------------------------------------------------------- |
| `node_type` | `NodeType` | — | Coarse-grained node type classification |
| `tag_name` | `String` | — | Raw HTML tag name (e.g., “div”, “h1”, “custom-element”) |
| `depth` | `usize` | — | Depth in the DOM tree (0 = root) |
| `index_in_parent` | `usize` | — | Index among siblings (0-based) |
| `parent_tag` | `Option<String>` | `None` | Parent element’s tag name (None if root) |
| `is_inline` | `bool` | — | Whether this element is treated as inline vs block |
***
### Other Types
[Section titled “Other Types”](#other-types)
#### StructuredData
[Section titled “StructuredData”](#structureddata)
Structured data block (JSON-LD, Microdata, or `RDFa`).
Represents machine-readable structured data found in the document. JSON-LD blocks are collected as raw JSON strings for flexibility.
| Field | Type | Default | Description |
| ------------- | -------------------- | ------- | --------------------------------------------------------------- |
| `data_type` | `StructuredDataType` | — | Type of structured data (JSON-LD, Microdata, `RDFa`) |
| `raw_json` | `String` | — | Raw JSON string (for JSON-LD) or serialized representation |
| `schema_type` | `Option<String>` | `None` | Schema type if detectable (e.g., “Article”, “Event”, “Product”) |
***
#### ImageDimensions
[Section titled “ImageDimensions”](#imagedimensions)
Image dimensions in pixels.
Binding-safe replacement for `(u32, u32)` tuples, which degrade to `list[list[str]]` when sanitized for cross-language binding generation. Used by both `ImageMetadata` and `InlineImage`.
| Field | Type | Default | Description |
| -------- | ----- | ------- | ----------------- |
| `width` | `u32` | — | Width in pixels. |
| `height` | `u32` | — | Height in pixels. |
***
#### DocumentStructure
[Section titled “DocumentStructure”](#documentstructure)
A structured document tree representing the semantic content of an HTML document.
Uses a flat node array with index-based parent/child references for efficient traversal.
| Field | Type | Default | Description |
| --------------- | ------------------- | ------- | --------------------------------------------------- |
| `nodes` | `Vec<DocumentNode>` | — | All nodes in document reading order. |
| `source_format` | `Option<String>` | `None` | The source format (always “html” for this library). |
***
#### TextAnnotation
[Section titled “TextAnnotation”](#textannotation)
A styling or semantic annotation that applies to a byte range within a node’s text.
Unlike `DocumentNode`, which captures block-level structure (headings, paragraphs, etc.), a `TextAnnotation` describes inline-level markup — bold, italic, links, code spans, and similar — that spans a contiguous run of bytes inside `DocumentNode.content`’s text field.
Byte offsets (`start`..`end`) are into the UTF-8 encoded text of the parent node. The range is half-open: `start` is inclusive and `end` is exclusive.
Multiple annotations on the same node can overlap (e.g. bold-italic text), and they are stored in the order they are encountered during DOM traversal.
See `AnnotationKind` for the full list of supported annotation types.
| Field | Type | Default | Description |
| ------- | ---------------- | ------- | ---------------------------------------------------------- |
| `start` | `u32` | — | Start byte offset (inclusive) into the parent node’s text. |
| `end` | `u32` | — | End byte offset (exclusive) into the parent node’s text. |
| `kind` | `AnnotationKind` | — | The type of annotation. |
***
#### ProcessingWarning
[Section titled “ProcessingWarning”](#processingwarning)
A non-fatal diagnostic produced during HTML conversion.
Warnings indicate that conversion completed but some content may have been handled differently than expected — for example, an image that could not be extracted, a truncated input, or malformed HTML that was repaired with best-effort parsing.
Conversion always succeeds (returns `ConversionResult`) even when warnings are present. Callers should inspect `warnings` and decide how to handle them based on their tolerance for partial results:
* **Logging pipelines**: emit each warning at `WARN` level and continue.
* **Strict pipelines**: treat any warning as a hard error by checking `result.warnings.is_empty()` before using the output.
See `WarningKind` for the full taxonomy of warning categories.
| Field | Type | Default | Description |
| --------- | ------------- | ------- | ------------------------------- |
| `message` | `String` | — | Human-readable warning message. |
| `kind` | `WarningKind` | — | The category of warning. |
***
#### VisitorHandle
[Section titled “VisitorHandle”](#visitorhandle)
Shareable, thread-safe handle to a user-provided HTML visitor implementation.
Pass an instance wrapped in this handle to `ConversionOptions` to customise how the HTML document is traversed and converted to Markdown. The handle may be cloned and shared across threads without additional synchronisation on the caller’s side.
*Opaque type — fields are not directly accessible.*
***
#### HtmlVisitor
[Section titled “HtmlVisitor”](#htmlvisitor)
Visitor for HTML→Markdown conversion.
Provide a visitor object whose methods customize the conversion behavior for any HTML element type. Override only the methods you care about; unimplemented methods default to `Continue` (emit the standard rendering).
Each callback returns one of:
* `Continue` (the default) — keep the standard rendering.
* `Skip` — drop the element from the output entirely.
* `PreserveHtml` — pass the original HTML through verbatim.
* `Custom(text)` — replace the rendering with `text`.
* `Error(message)` — abort conversion with `message`.
**Language idioms.** In Rust, return one of the `VisitResult` variants directly. In Python, Ruby, JavaScript/TypeScript, and other duck-typed bindings, define a plain class (no base class required) and return either a string (`"continue"`, `"skip"`, `"preserve_html"`) or a tagged map (`{"custom": "..."}`, `{"error": "..."}`) — the binding converts the return value to the corresponding `VisitResult` variant automatically.
##### Method Naming Convention
[Section titled “Method Naming Convention”](#method-naming-convention)
* `visit_*_start`: Called before entering an element (pre-order traversal)
* `visit_*_end`: Called after exiting an element (post-order traversal)
* `visit_*`: Called for specific element types (e.g., `visit_link`, `visit_image`)
##### Execution Order
[Section titled “Execution Order”](#execution-order)
For a typical element like `<div><p>text</p></div>`:
1. `visit_element_start` for `<div>`
2. `visit_element_start` for `<p>`
3. `visit_text` for “text”
4. `visit_element_end` for `<p>`
5. `visit_element_end` for `</div>`
##### Performance Notes
[Section titled “Performance Notes”](#performance-notes)
* `visit_text` is the most frequently called method (\~100+ times per document)
* Return `Continue` quickly for elements you don’t need to customize
* Avoid heavy computation in visitor methods; consider caching if needed
*Opaque type — fields are not directly accessible.*
***
### Enums
[Section titled “Enums”](#enums)
#### AnnotationKind
[Section titled “AnnotationKind”](#annotationkind)
The type of an inline text annotation.
Uses internally tagged representation (`"annotation_type": "bold"`) for JSON serialization.
| Variant | Wire value | Description |
| --------------- | --------------- | -------------------------------------------------------------------------------------------------- |
| `Bold` | `bold` | Bold / strong emphasis. |
| `Italic` | `italic` | Italic / emphasis. |
| `Underline` | `underline` | Underline. |
| `Strikethrough` | `strikethrough` | Strikethrough / deleted text. |
| `Code` | `code` | Inline code. |
| `Subscript` | `subscript` | Subscript text. |
| `Superscript` | `superscript` | Superscript text. |
| `Highlight` | `highlight` | Highlighted / marked text. |
| `Link` | `link` | A hyperlink sourced from an `<a href="...">` element. — Fields: `url`: `String`, `title`: `String` |
***
#### CodeBlockStyle
[Section titled “CodeBlockStyle”](#codeblockstyle)
Code block fence style in Markdown output.
Determines how code blocks (`<pre><code>`) are rendered in Markdown.
| Variant | Description |
| ----------- | --------------------------------------------------------------------------------- |
| `Indented` | Indented code blocks (4 spaces). `CommonMark` standard. |
| `Backticks` | Fenced code blocks with triple backticks. Default (GFM). Supports language hints. |
| `Tildes` | Fenced code blocks with tildes (\~\~\~). Supports language hints. |
***
#### HeadingStyle
[Section titled “HeadingStyle”](#headingstyle)
Heading style options for Markdown output.
Controls how headings (h1-h6) are rendered in the output Markdown.
| Variant | Description |
| ------------ | -------------------------------------------------- |
| `Underlined` | Underlined style (=== for h1, — for h2). |
| `Atx` | ATX style (# for h1, ## for h2, etc.). Default. |
| `AtxClosed` | ATX closed style (# title #, with closing hashes). |
***
#### HiddenContent
[Section titled “HiddenContent”](#hiddencontent)
Which text that a browser does not show at first the output holds.
The choice answers one question: can a reader get to the text? It does not depend on how the page hides it.
| Markup | `Drop` | `Reachable` | `All` |
| -------------------------------------------------------------------------------------- | ------- | ----------- | ------- |
| An element with the `hidden` attribute, any value (`hidden="until-found"` too) | dropped | kept | kept |
| An element with inline `display: none`, `visibility: hidden` or `font-size: 0` | dropped | kept | kept |
| An element of an inline `<svg>` with `display="none"` or `visibility="hidden"` | dropped | kept | kept |
| A declarative shadow root: a `<template>` whose `shadowrootmode` is `open` or `closed` | dropped | kept | kept |
| Any other `<template>`, and `<noscript>` | dropped | dropped | kept |
| `<script>`, `<style>`, comments, the value of `<input type="hidden">` | dropped | dropped | dropped |
`aria-hidden` is not hidden for this option. It takes an element away from assistive technology only: a browser still shows the element, so a reader sees its text, and every choice keeps it. One rule is older than this option and does not change with it: for an inline `<svg aria-hidden="true">` no choice writes the title, the description or the label of the graphic.
Every choice also keeps what the converter never treated as hidden: `inert`, a closed `<details>` or `<dialog>`, `<datalist>` and `<option>` text, and an element hidden by a class name, a style sheet rule, `opacity`, `content-visibility`, a zero size or an off-screen position. The converter reads the inline `style` attribute only. It does no layout and reads no style sheet, so it cannot tell that a rule in a style sheet hides an element.
A kept element converts like the same element without the attribute or style. Kept `<template>` and `<noscript>` content converts where it is written, as if the two tags were not there: a row in a `<template>` inside a `<table>` is a row of that table, and the content of a declarative shadow root comes before the other children of its host element. Slots are not resolved. `All` keeps `<noscript>` content with every preprocessing preset. A `<template>` or `<noscript>` in the document head holds metadata (`<link>`, `<meta>`, `<style>`), not text for a reader, and no choice keeps it. A document with no `<head>` tag has a head too: it starts at the doctype, at the `<html>` tag or at the first metadata element, and it ends where the body starts.
| Variant | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drop` | Drop the text a browser does not show at first. Default. |
| `Reachable` | Keep the text of elements that are in the page and that the page can show: an inactive tab panel, a collapsed section, an answer shown on a click, a declarative shadow root. |
| `All` | Keep what `Reachable` keeps, and the content of `<template>` and `<noscript>`. A reader gets to that text only after a script copies it into the page, or with scripting off. |
***
#### HighlightStyle
[Section titled “HighlightStyle”](#highlightstyle)
Highlight rendering style for `<mark>` elements.
Controls how highlighted text is rendered in Markdown output.
| Variant | Description |
| ------------- | ------------------------------------------------------------ |
| `DoubleEqual` | Double equals syntax (==text==). Default. Pandoc-compatible. |
| `Html` | Preserve as HTML (==text==). Original HTML tag. |
| `Bold` | Render as bold (**text**). Uses strong emphasis. |
| `None` | Strip formatting, render as plain text. No markup. |
***
#### ImageType
[Section titled “ImageType”](#imagetype)
Image source classification for proper handling and processing.
Determines whether an image is embedded (data URI), inline SVG, external, or relative.
| Variant | Wire value | Description |
| ----------- | ------------ | -------------------------------------------------- |
| `DataUri` | `data_uri` | Data URI embedded image (base64 or other encoding) |
| `InlineSvg` | `inline_svg` | Inline SVG element |
| `External` | `external` | External image URL (http/https) |
| `Relative` | `relative` | Relative image path |
***
#### InlineDataMedia
[Section titled “InlineDataMedia”](#inlinedatamedia)
What the output shows for an image, an embedded media element, or a link, whose address is an inline `data:` URL.
Applies to `<img>` (including its lazy-load attributes, its `srcset` candidates and the `<source>` elements of a `<picture>` around it), `<graphic>`, inline `<svg>`, `<video>`, `<audio>` (including their nested `<source>` elements), `<iframe>`, and a link (`<a href>`) whose own address is a `data:` URL.
With `AltTextOnly` or `DropElement`, an element that also has an address that is not `data:` uses that address instead. The document structure follows the markdown: a dropped image has no node, and an image written as its alt text has no address. A link whose only content the choice removed is dropped with it.
A link has no attribute separate from its own text to use as a caption, so `AltTextOnly` and `DropElement` do the same thing to a link’s `data:` address: write the link’s text with no destination. Unlike an image, a link’s text is never dropped along with the address.
| Variant | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Keep` | Write the `data:` URL as the destination, payload included. Default. |
| `AltTextOnly` | Write the alt text (the text of an `<svg>`, the fallback content for `<video>` and `<audio>`) without a destination. |
| `DropElement` | Write nothing for the element. |
***
#### LinkStyle
[Section titled “LinkStyle”](#linkstyle)
Link rendering style in Markdown output.
Controls whether links and images use inline `text` syntax or reference-style `[text][1]` syntax with definitions collected at the end.
| Variant | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Inline` | Inline links: `text`. Default. |
| `Reference` | Reference-style links: `[text][1]` with `[1]: url` at end of document. |
***
#### LinkType
[Section titled “LinkType”](#linktype)
Link classification based on href value and document context.
Used to categorize links during extraction for filtering and analysis.
| Variant | Wire value | Description |
| ---------- | ---------- | ----------------------------------------------------- |
| `Anchor` | `anchor` | Anchor link within same document (href starts with #) |
| `Internal` | `internal` | Internal link within same domain |
| `External` | `external` | External link to different domain |
| `Email` | `email` | Email link (mailto:) |
| `Phone` | `phone` | Phone link (tel:) |
| `Other` | `other` | Other protocol or unclassifiable |
***
#### ListIndentType
[Section titled “ListIndentType”](#listindenttype)
List indentation character type.
Controls whether list items are indented with spaces or tabs.
| Variant | Description |
| -------- | ----------------------------------------------------------------------------- |
| `Spaces` | Use spaces for indentation. Default. Width controlled by `list_indent_width`. |
| `Tabs` | Use tabs for indentation. |
***
#### NewlineStyle
[Section titled “NewlineStyle”](#newlinestyle)
Line break syntax in Markdown output.
Controls how soft line breaks (from `<br>` or line breaks in source) are rendered.
| Variant | Description |
| ----------- | ---------------------------------------------------------------------- |
| `Spaces` | Two trailing spaces at end of line. Default. Standard Markdown syntax. |
| `Backslash` | Backslash at end of line. Alternative Markdown syntax. |
***
#### NodeContent
[Section titled “NodeContent”](#nodecontent)
The semantic content type of a document node.
Uses internally tagged representation (`"node_type": "heading"`) for JSON serialization.
| Variant | Wire value | Description |
| ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Heading` | `heading` | A heading element (h1-h6). — Fields: `level`: `u8`, `text`: `String` |
| `Paragraph` | `paragraph` | A paragraph of text. — Fields: `text`: `String` |
| `List` | `list` | A list container (ordered or unordered). Children are `ListItem` nodes. — Fields: `ordered`: `bool` |
| `ListItem` | `list_item` | A single list item. — Fields: `text`: `String` |
| `Table` | `table` | A table with structured cell data. — Fields: `grid`: `TableGrid` |
| `Image` | `image` | An image element. — Fields: `description`: `String`, `src`: `String`, `image_index`: `u32` |
| `Code` | `code` | A code block or inline code. — Fields: `text`: `String`, `language`: `String` |
| `Quote` | `quote` | A block quote container. |
| `DefinitionList` | `definition_list` | A definition list container. |
| `DefinitionItem` | `definition_item` | A definition list entry with term and description. — Fields: `term`: `String`, `definition`: `String` |
| `RawBlock` | `raw_block` | A raw block preserved as-is (e.g. `<script>`, `<style>` content). — Fields: `format`: `String`, `content`: `String` |
| `MetadataBlock` | `metadata_block` | A block of key-value metadata pairs (from `<head>` meta tags). — Fields: `entries`: `Vec<MetadataEntry>` |
| `Group` | `group` | A section grouping container (auto-generated from heading hierarchy). — Fields: `label`: `String`, `heading_level`: `u8`, `heading_text`: `String` |
***
#### NodeType
[Section titled “NodeType”](#nodetype)
Node type enumeration covering all HTML element types.
This enum categorizes all HTML elements that the converter recognizes, providing a coarse-grained classification for visitor dispatch.
| Variant | Description |
| ----------------------- | ---------------------------------------------- |
| `Text` | Text node (most frequent - 100+ per document) |
| `Element` | Generic element node |
| `Heading` | Heading elements (h1-h6) |
| `Paragraph` | Paragraph element |
| `Div` | Generic div container |
| `Blockquote` | Blockquote element |
| `Pre` | Preformatted text block |
| `Hr` | Horizontal rule |
| `List` | Ordered or unordered list (ul, ol) |
| `ListItem` | List item (li) |
| `DefinitionList` | Definition list (dl) |
| `DefinitionTerm` | Definition term (dt) |
| `DefinitionDescription` | Definition description (dd) |
| `Table` | Table element |
| `TableRow` | Table row (tr) |
| `TableCell` | Table cell (td, th) |
| `TableHeader` | Table header cell (th) |
| `TableBody` | Table body (tbody) |
| `TableHead` | Table head (thead) |
| `TableFoot` | Table foot (tfoot) |
| `Link` | Anchor link (a) |
| `Image` | Image (img) |
| `Strong` | Strong/bold (strong, b) |
| `Em` | Emphasis/italic (em, i) |
| `Code` | Inline code (code) |
| `Strikethrough` | Strikethrough (s, del, strike) |
| `Underline` | Underline (u, ins) |
| `Subscript` | Subscript (sub) |
| `Superscript` | Superscript (sup) |
| `Mark` | Mark/highlight (mark) |
| `Small` | Small text (small) |
| `Br` | Line break (br) |
| `Span` | Span element |
| `Article` | Article element |
| `Section` | Section element |
| `Nav` | Navigation element |
| `Aside` | Aside element |
| `Header` | Header element |
| `Footer` | Footer element |
| `Main` | Main element |
| `Figure` | Figure element |
| `Figcaption` | Figure caption |
| `Time` | Time element |
| `Details` | Details element |
| `Summary` | Summary element |
| `Form` | Form element |
| `Input` | Input element |
| `Select` | Select element |
| `Option` | Option element |
| `Button` | Button element |
| `Textarea` | Textarea element |
| `Label` | Label element |
| `Fieldset` | Fieldset element |
| `Legend` | Legend element |
| `Audio` | Audio element |
| `Video` | Video element |
| `Picture` | Picture element |
| `Source` | Source element |
| `Iframe` | Iframe element |
| `Svg` | SVG element |
| `Canvas` | Canvas element |
| `Ruby` | Ruby annotation |
| `Rt` | Ruby text |
| `Rp` | Ruby parenthesis |
| `Abbr` | Abbreviation |
| `Kbd` | Keyboard input |
| `Samp` | Sample output |
| `Var` | Variable |
| `Cite` | Citation |
| `Q` | Quote |
| `Del` | Deleted text |
| `Ins` | Inserted text |
| `Data` | Data element |
| `Meter` | Meter element |
| `Progress` | Progress element |
| `Output` | Output element |
| `Template` | Template element |
| `Slot` | Slot element |
| `Html` | HTML root element |
| `Head` | Head element |
| `Body` | Body element |
| `Title` | Title element |
| `Meta` | Meta element |
| `LinkTag` | Link element (not anchor) |
| `Style` | Style element |
| `Script` | Script element |
| `Base` | Base element |
| `Custom` | Custom element (web components) or unknown tag |
***
#### OutputFormat
[Section titled “OutputFormat”](#outputformat)
Output format for conversion.
Specifies the target markup language format for the conversion output.
| Variant | Description |
| ---------- | ----------------------------------------------------- |
| `Markdown` | Standard Markdown (`CommonMark` compatible). Default. |
| `Djot` | Djot lightweight markup language. |
| `Plain` | Plain text output (no markup, visible text only). |
***
#### PreprocessingPreset
[Section titled “PreprocessingPreset”](#preprocessingpreset)
HTML preprocessing aggressiveness level.
Controls the extent of cleanup performed before conversion. Higher levels remove more elements.
| Variant | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `Minimal` | Minimal cleanup. Remove only essential noise (scripts, styles). |
| `Standard` | Standard cleanup. Default. Removes navigation, forms, and other auxiliary content. |
| `Aggressive` | Aggressive cleanup. Remove extensive non-content elements and structure. |
***
#### StructuredDataType
[Section titled “StructuredDataType”](#structureddatatype)
Structured data format type.
Identifies the schema/format used for structured data markup.
| Variant | Wire value | Description |
| ----------- | ----------- | ---------------------------------------------------------- |
| `JsonLd` | `json_ld` | JSON-LD (JSON for Linking Data) script blocks |
| `Microdata` | `microdata` | HTML5 Microdata attributes (itemscope, itemtype, itemprop) |
| `RDFa` | `rdfa` | RDF in Attributes (`RDFa`) markup |
***
#### TextDirection
[Section titled “TextDirection”](#textdirection)
Text directionality of document content.
Corresponds to the HTML `dir` attribute and `bdi` element directionality.
| Variant | Wire value | Description |
| ------------- | ---------- | ---------------------------------------------------- |
| `LeftToRight` | `ltr` | Left-to-right text flow (default for Latin scripts) |
| `RightToLeft` | `rtl` | Right-to-left text flow (Hebrew, Arabic, Urdu, etc.) |
| `Auto` | `auto` | Automatic directionality detection |
***
#### TierStrategy
[Section titled “TierStrategy”](#tierstrategy)
Controls which conversion tier is used.
| Variant | Wire value | Description |
| ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auto` | `auto` | Automatically pick the best tier for the input (default). Runs the classifier against the prescan report and uses Tier-1 when eligible; falls back to Tier-2 on bail or when the classifier routes to Tier-2. |
| `Tier2` | `tier2` | Always use the Tier-2 (`tl::parse` + walk) path, skipping Tier-1. |
| `Tier1` | `tier1` | Force the Tier-1 byte scanner; if it bails, fall back to Tier-2. Testkit-only; not stable API. |
***
#### UrlEscapeStyle
[Section titled “UrlEscapeStyle”](#urlescapestyle)
URL encoding strategy for link and image destinations.
Controls how special characters in URL destinations are handled when they require escaping to produce valid Markdown.
The `Angle` variant (default) wraps the destination in angle brackets: `[text](<url with spaces>)`. This is the CommonMark-specified escape hatch but breaks when the URL itself contains `>`.
The `Percent` variant percent-encodes every character that is not an RFC 3986 unreserved character or `/`, producing a destination safe for all Markdown parsers: `[text](url%20with%20spaces)`.
| Variant | Description |
| --------- | ----------------------------------------------------------------------------- |
| `Angle` | Wrap destinations that contain spaces or newlines in angle brackets. Default. |
| `Percent` | Percent-encode all characters that are not RFC 3986 unreserved or `/`. |
***
#### VisitResult
[Section titled “VisitResult”](#visitresult)
Result of a visitor callback.
Allows visitors to control the conversion flow by either proceeding with default behavior, providing custom output, skipping elements, preserving HTML, or signaling errors.
| Variant | Wire value | Description |
| -------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Continue` | `continue` | Continue with default conversion behavior |
| `Custom` | `custom` | Replace default output with custom markdown The visitor takes full responsibility for the markdown output of this node and its children. — Fields: `output`: `String` |
| `Skip` | `skip` | Skip this element entirely (don’t output anything) The element and all its children are ignored in the output. |
| `PreserveHtml` | `preserve_html` | Preserve original HTML (don’t convert to markdown) The element’s raw HTML is included verbatim in the output. |
| `Error` | `error` | Stop conversion with an error The conversion process halts and returns this error message. — Fields: `output`: `String` |
***
#### WarningKind
[Section titled “WarningKind”](#warningkind)
Categories of processing warnings.
| Variant | Wire value | Description |
| ----------------------- | ------------------------- | ---------------------------------------------------------------------------- |
| `ImageExtractionFailed` | `image_extraction_failed` | An image could not be extracted (e.g. invalid data URI, unsupported format). |
| `EncodingFallback` | `encoding_fallback` | The input encoding was not recognized; fell back to UTF-8. |
| `TruncatedInput` | `truncated_input` | The input was truncated due to size limits. |
| `MalformedHtml` | `malformed_html` | The HTML was malformed but processing continued with best effort. |
| `SanitizationApplied` | `sanitization_applied` | Sanitization was applied to remove potentially unsafe content. |
| `DepthLimitExceeded` | `depth_limit_exceeded` | DOM traversal was truncated because `max_depth` was exceeded. |
***
#### WhitespaceMode
[Section titled “WhitespaceMode”](#whitespacemode)
Whitespace handling strategy during conversion.
Determines how sequences of whitespace characters (spaces, tabs, newlines) are processed.
| Variant | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Normalized` | Collapse multiple whitespace characters to single spaces. Default. Matches browser behavior. |
| `Strict` | Preserve all whitespace exactly as it appears in the HTML. |
***
# Table Extraction
Every call to `convert()` populates `result.tables` with one entry per `<table>` found in the input. Each entry has both a rendered Markdown string and a structured cell grid, so you can embed the Markdown in downstream documents or walk the grid for analysis without re-parsing.
Table extraction runs on every call. There is no opt-in flag. Use JSON output with `--no-content` in the CLI, or ignore `result.content` in library code, when you only want table data.
## TableData
[Section titled “TableData”](#tabledata)
`result.tables` is a `Vec<TableData>` (or the equivalent list in each binding).
| Field | Type | Description |
| ---------- | ----------- | ------------------------------------------------------------------------------------ |
| `grid` | `TableGrid` | Structured cell grid. |
| `markdown` | `String` | The Markdown rendering of this table, identical to what appears in `result.content`. |
## TableGrid
[Section titled “TableGrid”](#tablegrid)
| Field | Type | Description |
| ------- | --------------- | ----------------------------------------------------------------------------------------------- |
| `rows` | `u32` | Number of rows in the table. |
| `cols` | `u32` | Number of columns in the table. |
| `cells` | `Vec<GridCell>` | Flat list of cells. May be shorter than `rows * cols` when cells span multiple rows or columns. |
## GridCell
[Section titled “GridCell”](#gridcell)
| Field | Type | Description |
| ----------- | -------- | -------------------------------------------------------- |
| `content` | `String` | Cell text. Inline formatting is flattened to plain text. |
| `row` | `u32` | 0-indexed row position. |
| `col` | `u32` | 0-indexed column position. |
| `row_span` | `u32` | How many rows the cell occupies. Defaults to `1`. |
| `col_span` | `u32` | How many columns the cell occupies. Defaults to `1`. |
| `is_header` | `bool` | `true` for `<th>`, `false` for `<td>`. |
## Basic Extraction
[Section titled “Basic Extraction”](#basic-extraction)
* Rust
```rust
use html_to_markdown_rs::{ConversionOptions, convert};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let html = r#"
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
"#;
// `tables` is collected alongside the document tree, so it must be enabled.
let options = ConversionOptions::builder().include_document_structure(true).build();
let result = convert(html, Some(options))?;
for table in &result.tables {
for cell in &table.grid.cells {
let kind = if cell.is_header { "Header" } else { "Cell" };
println!(" {kind} (r{},c{}): {}", cell.row, cell.col, cell.content);
}
}
Ok(())
}
```
* Python
```python
from html_to_markdown import ConversionOptions, convert
html = """
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
"""
# `tables` is collected alongside the document tree, so it must be enabled.
result = convert(html, ConversionOptions(include_document_structure=True))
for table in result.tables:
for cell in table.grid.cells:
prefix = "Header" if cell.is_header else "Cell"
print(f" {prefix} (r{cell.row},c{cell.col}): {cell.content}")
```
* TypeScript
```typescript
import { convert } from "@xberg-io/html-to-markdown";
const html = `
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
`;
const result = convert(html, { includeDocumentStructure: true });
for (const table of result.tables ?? []) {
for (const cell of table.grid.cells ?? []) {
const kind = cell.isHeader ? "Header" : "Cell";
console.log(` ${kind} (r${cell.row},c${cell.col}): ${cell.content}`);
}
}
```
* Go
```go
import (
"fmt"
"log"
htmltomarkdown "github.com/xberg-io/html-to-markdown/packages/go/v3"
)
html := `
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
`
result, err := htmltomarkdown.Convert(html, &htmltomarkdown.ConversionOptions{
IncludeDocumentStructure: true,
})
if err != nil {
log.Fatal(err)
}
for _, table := range result.Tables {
for _, cell := range table.Grid.Cells {
kind := "Cell"
if cell.IsHeader {
kind = "Header"
}
fmt.Printf(" %s (r%d,c%d): %s\n", kind, cell.Row, cell.Col, cell.Content)
}
}
```
* Ruby
```ruby
require 'html_to_markdown'
html = <<~HTML
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
HTML
# Tables are only populated when `include_document_structure` is enabled.
result = HtmlToMarkdown.convert(html, include_document_structure: true)
result.tables.each do |table|
table.grid.cells.group_by(&:row).each do |_row, cells|
prefix = cells.first.is_header ? "Header" : "Row"
puts " #{prefix}: #{cells.map(&:content).join(', ')}"
end
end
```
* PHP
```php
use HtmlToMarkdown\HtmlToMarkdownApi;
use HtmlToMarkdown\ConversionOptions;
$html = <<<HTML
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
HTML;
// tables are populated only when includeDocumentStructure is enabled.
$options = ConversionOptions::from_json(json_encode(['includeDocumentStructure' => true]));
$result = HtmlToMarkdownApi::convert($html, $options);
foreach ($result->getTables() as $table) {
foreach ($table->getGrid()->getCells() as $cell) {
$kind = $cell->isHeader ? 'Header' : 'Cell';
echo " {$kind} (r{$cell->row},c{$cell->col}): {$cell->content}\n";
}
}
```
* Java
```java
import io.xberg.htmltomarkdown.HtmlToMarkdown;
import io.xberg.htmltomarkdown.ConversionOptions;
import io.xberg.htmltomarkdown.ConversionResult;
import io.xberg.htmltomarkdown.HtmlToMarkdownRsException;
public class TableExample {
public static void main(String[] args) throws HtmlToMarkdownRsException {
String html = """
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
""";
ConversionOptions options = ConversionOptions.builder()
.withIncludeDocumentStructure(true)
.build();
ConversionResult result = HtmlToMarkdown.convert(html, options);
for (var table : result.tables()) {
for (var cell : table.grid().cells()) {
String prefix = Boolean.TRUE.equals(cell.isHeader()) ? "Header" : "Cell";
System.out.printf(" %s (r%d,c%d): %s%n", prefix, cell.row(), cell.col(), cell.content());
}
}
}
}
```
* C#
```csharp
using HtmlToMarkdown;
var html = @"
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>";
var options = new ConversionOptions { IncludeDocumentStructure = true };
var result = HtmlToMarkdownConverter.Convert(html, options);
foreach (var table in result.Tables)
{
foreach (var cell in table.Grid.Cells)
{
var kind = cell.IsHeader ? "Header" : "Cell";
Console.WriteLine($" {kind} (r{cell.Row},c{cell.Col}): {cell.Content}");
}
}
```
* Elixir
```elixir
html = """
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
"""
opts = %HtmlToMarkdown.ConversionOptions{include_document_structure: true}
{:ok, result} = HtmlToMarkdown.convert(html, opts)
for %HtmlToMarkdown.TableData{grid: grid} <- result.tables do
grid.cells
|> Enum.group_by(& &1.row)
|> Enum.sort_by(fn {row, _cells} -> row end)
|> Enum.each(fn {_row, cells} ->
cells = Enum.sort_by(cells, & &1.col)
prefix = if hd(cells).is_header, do: "Header", else: "Row"
values = Enum.map(cells, & &1.content)
IO.puts(" #{prefix}: #{Enum.join(values, ", ")}")
end)
end
```
* R
```r
library(htmltomarkdown)
html <- "
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
"
# `tables` is collected alongside the document tree, so it must be enabled.
opts <- conversion_options(include_document_structure = TRUE)
result <- convert(html, opts)
for (table in result$tables) {
for (cell in table$grid$cells) {
prefix <- if (cell$is_header) "Header" else "Cell"
cat(sprintf(" %s (r%d,c%d): %s\n", prefix, cell$row, cell$col, cell$content))
}
}
```
* C
```c
#include "html_to_markdown.h"
#include <stdio.h>
int main(void) {
const char *html =
"<table>"
"<tr><th>Name</th><th>Age</th></tr>"
"<tr><td>Alice</td><td>30</td></tr>"
"<tr><td>Bob</td><td>25</td></tr>"
"</table>";
/* include_document_structure must be enabled to populate result.tables;
* with the default options the "tables" array in the JSON is empty. */
HTMAlefHandle options =
htm_conversion_options_from_json("{\"include_document_structure\":true}");
if (options == 0) {
fprintf(stderr, "options failed: %s\n", htm_last_error_context());
return 1;
}
HTMAlefHandle result = htm_convert(html, options);
htm_conversion_options_free(options);
if (result == 0) {
fprintf(stderr, "convert failed: %s\n", htm_last_error_context());
return 1;
}
char *json = htm_conversion_result_to_json(result);
if (json != NULL) {
printf("%s\n", json); /* contains a populated "tables" array */
htm_free_string(json);
}
htm_conversion_result_free(result);
return 0;
}
```
* WASM
```javascript
import { convert, WasmConversionOptions } from "@xberg-io/html-to-markdown-wasm";
const html = `
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
`;
const options = WasmConversionOptions.default();
options.includeDocumentStructure = true;
const result = convert(html, options);
for (const table of result.tables) {
for (const cell of table.grid.cells) {
const kind = cell.isHeader ? "Header" : "Cell";
console.log(` ${kind} (r${cell.row},c${cell.col}): ${cell.content}`);
}
}
```
* Swift
```swift
import HtmlToMarkdown
let options = try conversionOptionsFromJson(
"{\"include_document_structure\":true}"
)
let html = """
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
"""
let result = try convert(html: html, options: options)
for table in result.tables {
print("Markdown:", table.markdown)
let grid = table.grid
print("Grid: \(grid.rows) rows x \(grid.cols) cols")
for cell in grid.cells {
let kind = cell.isHeader ? "Header" : "Cell"
print(" \(kind) (r\(cell.row),c\(cell.col)): \(cell.content)")
}
}
```
* Dart
```dart
import 'package:h2m/h2m.dart';
import 'package:h2m/src/html_to_markdown_rs_bridge_generated/frb_generated.dart'
show RustLib;
Future<void> main() async {
await RustLib.init();
const html = '''
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
''';
final options = await createConversionOptionsFromJson(
json: '{"include_document_structure":true}',
);
final result = await H2mBridge.convert(html, options: options);
for (final table in result.tables) {
for (final cell in table.grid.cells) {
final kind = cell.isHeader ? 'Header' : 'Cell';
print(' $kind (r${cell.row},c${cell.col}): ${cell.content}');
}
}
}
```
* Kotlin Android
```kotlin
import io.xberg.android.ConversionOptions
import io.xberg.android.HtmlToMarkdown
fun main() {
val html = """
<table>
<tr><th>Name</th><th>Age</th></tr>
<tr><td>Alice</td><td>30</td></tr>
<tr><td>Bob</td><td>25</td></tr>
</table>
""".trimIndent()
// Table extraction requires `includeDocumentStructure = true` — without it,
// `result.tables` is always empty even for table-heavy HTML.
val options = ConversionOptions(includeDocumentStructure = true)
val result = HtmlToMarkdown.convert(html, options)
for (table in result.tables) {
println(table.markdown)
for (cell in table.grid.cells) {
val kind = if (cell.isHeader) "Header" else "Cell"
println(" $kind (r${cell.row},c${cell.col}): ${cell.content}")
}
}
}
```
* Zig
```zig
const std = @import("std");
const html_to_markdown = @import("html_to_markdown_rs");
pub fn main() !void {
var gpa: std.heap.DebugAllocator(.{}) = .init;
defer _ = gpa.deinit();
const allocator = gpa.allocator();
const html =
\\<table>
\\ <tr><th>Name</th><th>Age</th></tr>
\\ <tr><td>Alice</td><td>30</td></tr>
\\ <tr><td>Bob</td><td>25</td></tr>
\\</table>
;
// Tables are only populated in `result.tables` when
// `include_document_structure` is enabled.
const result_json = try html_to_markdown.convert(html, "{\"include_document_structure\":true}");
defer std.heap.c_allocator.free(result_json);
var parsed = try std.json.parseFromSlice(std.json.Value, allocator, result_json, .{});
defer parsed.deinit();
const tables = parsed.value.object.get("tables").?.array;
std.debug.print("Extracted {d} table(s)\n", .{tables.items.len});
for (tables.items, 0..) |table, i| {
const grid = table.object.get("grid").?.object;
const rows = grid.get("rows").?.integer;
const cols = grid.get("cols").?.integer;
const markdown = table.object.get("markdown").?.string;
std.debug.print("Table {d}: {d}x{d}\n{s}\n", .{ i, rows, cols, markdown });
for (grid.get("cells").?.array.items) |cell| {
const content = cell.object.get("content").?.string;
const row = cell.object.get("row").?.integer;
const col = cell.object.get("col").?.integer;
const is_header = cell.object.get("is_header").?.bool;
std.debug.print(" [{d},{d}] header={} '{s}'\n", .{ row, col, is_header, content });
}
}
}
```
## Relationship to `result.content`
[Section titled “Relationship to result.content”](#relationship-to-resultcontent)
The Markdown in `TableData.markdown` is the same Markdown that appears inline inside `result.content`. The grid exists for code that needs cell-level access: headers vs body rows, span detection, or programmatic lookup by `(row, col)`.
If the input has no tables, `result.tables` is an empty list. If the output format is `"plain"`, tables are still extracted and their grids are still populated; only the rendering in `result.content` changes.
## Spans
[Section titled “Spans”](#spans)
A cell with `row_span > 1` or `col_span > 1` appears once in `cells`, positioned at its top-left coordinates. Downstream code that iterates by `(row, col)` should respect the span or use the spans to reconstruct a dense grid.
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Usage
Output is not sanitized
`convert()` does not sanitize its output. The returned Markdown can contain raw HTML, `javascript:`/`data:` URLs, and other content carried over verbatim from the input. Treat conversion output as untrusted and sanitize it in whatever renders it (browser, Markdown-to-HTML pipeline, etc.) before displaying attacker-controlled input. There is also no cap on input size — deeply nested input is bounded by `max_depth`, but there is no limit on total input length. See [Security](https://github.com/xberg-io/html-to-markdown/blob/main/SECURITY.md).
## Basic Conversion
[Section titled “Basic Conversion”](#basic-conversion)
`convert()` accepts an HTML string and returns a `ConversionResult`.
* Rust
```rust
use html_to_markdown_rs::convert;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>";
let result = convert(html, None)?;
let markdown = result.content.unwrap_or_default();
println!("{markdown}");
Ok(())
}
```
* Python
```python
from html_to_markdown import convert
html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
result = convert(html)
markdown = result.content
```
* TypeScript
```typescript
import { convert } from "@xberg-io/html-to-markdown";
const result = convert("<h1>Hello World</h1>");
const markdown = result.content ?? "";
console.log(markdown); // # Hello World
```
* Go
```go
package main
import (
"fmt"
"log"
htmltomarkdown "github.com/xberg-io/html-to-markdown/packages/go/v3"
)
func main() {
html := "<h1>Hello World</h1><p>This is a paragraph.</p>"
result, err := htmltomarkdown.Convert(html, nil)
if err != nil {
log.Fatal(err)
}
if result.Content != nil {
fmt.Println(*result.Content)
}
}
```
* Ruby
```ruby
require 'html_to_markdown'
html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
result = HtmlToMarkdown.convert(html)
markdown = result.content
```
* PHP
```php
use HtmlToMarkdown\HtmlToMarkdownApi;
$result = HtmlToMarkdownApi::convert('<h1>Hello</h1><p>This is <strong>fast</strong>!</p>');
echo $result->content;
```
* Java
```java
import io.xberg.htmltomarkdown.HtmlToMarkdown;
import io.xberg.htmltomarkdown.ConversionResult;
import io.xberg.htmltomarkdown.HtmlToMarkdownRsException;
public class Example {
public static void main(String[] args) throws HtmlToMarkdownRsException {
String html = "<h1>Hello World</h1><p>This is a <strong>test</strong>.</p>";
ConversionResult result = HtmlToMarkdown.convert(html);
System.out.println(result.content());
}
}
```
* C#
```csharp
using HtmlToMarkdown;
var html = "<h1>Hello World</h1><p>This is a paragraph.</p>";
var result = HtmlToMarkdownConverter.Convert(html, null);
Console.WriteLine(result.Content);
```
* Elixir
```elixir
{:ok, result} = HtmlToMarkdown.convert("<h1>Hello</h1><p>This is <strong>fast</strong>!</p>")
IO.puts(result.content)
```
* R
```r
library(htmltomarkdown)
html <- "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
result <- convert(html)
markdown <- result$content
cat(markdown)
```
* C
```c
#include "html_to_markdown.h"
#include <stdio.h>
int main(void) {
HTMAlefHandle result = htm_convert("<h1>Hello</h1><p>World</p>", 0);
if (result == 0) {
fprintf(stderr, "convert failed (code %d): %s\n",
htm_last_error_code(), htm_last_error_context());
return 1;
}
char *content = htm_conversion_result_content(result);
if (content != NULL) {
printf("%s\n", content);
htm_free_string(content);
}
htm_conversion_result_free(result);
return 0;
}
```
* WASM
```javascript
import { convert } from "@xberg-io/html-to-markdown-wasm";
const html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>";
const result = convert(html);
const markdown = result.content;
console.log(markdown);
```
* Swift
```swift
import HtmlToMarkdown
let html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
let result = try convert(html: html)
let markdown = result.content ?? ""
print(markdown)
```
* Dart
```dart
import 'package:h2m/h2m.dart';
import 'package:h2m/src/html_to_markdown_rs_bridge_generated/frb_generated.dart'
show RustLib;
Future<void> main() async {
await RustLib.init();
const html = '<h1>Hello</h1><p>This is <strong>fast</strong>!</p>';
final result = await H2mBridge.convert(html);
print(result.content);
}
```
* Kotlin Android
```kotlin
import io.xberg.android.HtmlToMarkdown
val html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
val result = HtmlToMarkdown.convert(html)
val markdown: String? = result.content
```
* Zig
```zig
const std = @import("std");
const html_to_markdown = @import("html_to_markdown_rs");
pub fn main() !void {
const html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>";
const result_json = try html_to_markdown.convert(html, null);
defer std.heap.c_allocator.free(result_json);
// result_json is the ConversionResult serialised as JSON; parse with
// std.json or read the `content` field directly.
std.debug.print("{s}\n", .{result_json});
}
```
## ConversionResult Fields
[Section titled “ConversionResult Fields”](#conversionresult-fields)
Every call to `convert()` returns a `ConversionResult` with the following fields:
| Field | Type | Description |
| ---------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `Optional<String>` | The converted text (Markdown, Djot, or plain). There is no extraction-only `none` output format. |
| `document` | `Optional<DocumentStructure>` | Structured document tree (headings, paragraphs, lists, tables). Only populated when `include_document_structure` is `true`. |
| `metadata` | `HtmlMetadata` | Extracted HTML metadata (title, description, Open Graph, Twitter Card, JSON-LD, links, images). |
| `tables` | `Vec<TableData>` | Extracted tables with full grid data (headers, rows, colspan/rowspan). |
| `images` | `Vec<ExtractedImage>` | Inline image extraction output. Rust and WASM expose it when built with `inline-images`; generated native bindings may omit the Rust-only image payload. |
| `warnings` | `Vec<ProcessingWarning>` | Non-fatal warnings raised during conversion. |
## Using Options
[Section titled “Using Options”](#using-options)
Control output style, metadata extraction, and more via `ConversionOptions`.
* Rust
```rust
use html_to_markdown_rs::{ConversionOptions, HeadingStyle, convert};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let options = ConversionOptions::builder()
.heading_style(HeadingStyle::Atx)
.skip_images(true)
.build();
let result = convert("<h1>Hello</h1><img src='pic.jpg'>", Some(options))?;
println!("{}", result.content.unwrap_or_default());
Ok(())
}
```
* Python
```python
from html_to_markdown import ConversionOptions, convert
html = "<h1>Hello</h1><p>This is <strong>formatted</strong> content.</p>"
options = ConversionOptions(
heading_style="atx",
list_indent_width=2,
)
result = convert(html, options)
markdown = result.content
```
* TypeScript
```typescript
import { convert, ConversionOptions, HeadingStyle } from "@xberg-io/html-to-markdown";
const options: ConversionOptions = {
headingStyle: HeadingStyle.Atx,
listIndentWidth: 2,
wrap: true,
};
const result = convert("<h1>Title</h1><p>Content</p>", options);
const markdown = result.content;
```
* Go
```go
package main
import (
"fmt"
"log"
htmltomarkdown "github.com/xberg-io/html-to-markdown/packages/go/v3"
)
func main() {
html := "<h1>Hello</h1><p>Welcome</p>"
width := uint(80)
opts := htmltomarkdown.ConversionOptions{
Wrap: true,
WrapWidth: &width,
}
result, err := htmltomarkdown.Convert(html, &opts)
if err != nil {
log.Fatalf("Conversion failed: %v", err)
}
if result.Content != nil {
fmt.Println(*result.Content)
}
}
```
* Ruby
```ruby
require 'html_to_markdown'
html = "<h1>Hello</h1><p>This is <strong>fast</strong>!</p>"
result = HtmlToMarkdown.convert(html, heading_style: :atx, code_block_style: :fenced)
markdown = result.content
```
* PHP
```php
use HtmlToMarkdown\HtmlToMarkdownApi;
use HtmlToMarkdown\ConversionOptions;
$options = ConversionOptions::from_json(json_encode([
'headingStyle' => 'Atx',
'listIndentWidth' => 2,
]));
$result = HtmlToMarkdownApi::convert('<h1>Hello</h1>', $options);
echo $result->content;
```
* Java
```java
import io.xberg.htmltomarkdown.HtmlToMarkdown;
import io.xberg.htmltomarkdown.ConversionOptions;
import io.xberg.htmltomarkdown.ConversionResult;
import io.xberg.htmltomarkdown.HtmlToMarkdownRsException;
public class MetadataExample {
public static void main(String[] args) throws HtmlToMarkdownRsException {
String html = "<html><head><title>My Page "
+ "Welcome Link ";
ConversionOptions options = ConversionOptions.builder()
.withExtractMetadata(true)
.build();
ConversionResult result = HtmlToMarkdown.convert(html, options);
System.out.println("Markdown: " + result.content());
System.out.println("Title: " + result.metadata().document().title());
System.out.println("Headers: " + result.metadata().headers().size());
System.out.println("Links: " + result.metadata().links().size());
}
}
```
* C#
```csharp
using HtmlToMarkdown;
var options = new ConversionOptions
{
HeadingStyle = HeadingStyle.Atx,
Wrap = true,
WrapWidth = 80,
ListIndentWidth = 4,
};
var html = "Hello This is formatted content.
";
var result = HtmlToMarkdownConverter.Convert(html, options);
Console.WriteLine(result.Content);
```
* Elixir
```elixir
opts = %HtmlToMarkdown.ConversionOptions{wrap: true, wrap_width: 40}
{:ok, result} = HtmlToMarkdown.convert("Hello World
", opts)
IO.puts(result.content)
```
* R
```r
library(htmltomarkdown)
opts <- conversion_options(
heading_style = "Atx",
wrap = TRUE,
wrap_width = 80L
)
result <- convert("Hello World
", opts)
cat(result$content)
```
* C
```c
#include "html_to_markdown.h"
#include
int main(void) {
HTMAlefHandle options =
htm_conversion_options_from_json("{\"heading_style\":\"atx\",\"wrap\":true}");
if (options == 0) {
fprintf(stderr, "options failed: %s\n", htm_last_error_context());
return 1;
}
HTMAlefHandle result = htm_convert("Title Paragraph
", options);
htm_conversion_options_free(options);
if (result == 0) {
fprintf(stderr, "convert failed: %s\n", htm_last_error_context());
return 1;
}
char *content = htm_conversion_result_content(result);
if (content != NULL) {
printf("%s\n", content);
htm_free_string(content);
}
htm_conversion_result_free(result);
return 0;
}
```
* WASM
```javascript
import { convert, WasmConversionOptions, WasmHeadingStyle } from "@xberg-io/html-to-markdown-wasm";
const options = WasmConversionOptions.default();
options.headingStyle = WasmHeadingStyle.Atx;
options.skipImages = true;
const result = convert('Hello Hello This is formatted content.
"
let result = try convert(html: html, options: options)
let markdown = result.content ?? ""
print(markdown)
```
* Dart
```dart
import 'package:h2m/h2m.dart';
import 'package:h2m/src/html_to_markdown_rs_bridge_generated/frb_generated.dart'
show RustLib;
Future main() async {
await RustLib.init();
final options = await createConversionOptionsFromJson(
json: '{"heading_style":"atx","list_indent_width":2,"wrap":true}',
);
const html = 'Hello This is formatted content.
';
final result = await H2mBridge.convert(html, options: options);
print(result.content);
}
```
* Kotlin Android
```kotlin
import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.databind.PropertyNamingStrategies
import com.fasterxml.jackson.module.kotlin.registerKotlinModule
import io.xberg.android.ConversionOptions
import io.xberg.android.HtmlToMarkdown
val mapper = ObjectMapper()
.registerKotlinModule()
.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE)
val options = mapper.readValue(
"{\"heading_style\":\"Atx\",\"list_indent_width\":2,\"wrap\":true}",
ConversionOptions::class.java,
)
val html = "Hello This is formatted content.
"
val result = HtmlToMarkdown.convert(html, options)
val markdown: String? = result.content
```
* Zig
```zig
const std = @import("std");
const html_to_markdown = @import("html_to_markdown_rs");
pub fn main() !void {
const html = "Hello This is formatted content.
";
const options_json =
\\{"heading_style":"atx","list_indent_width":2,"wrap":true}
;
const result_json = try html_to_markdown.convert(html, options_json);
defer std.heap.c_allocator.free(result_json);
std.debug.print("{s}\n", .{result_json});
}
```
## Metadata Extraction
[Section titled “Metadata Extraction”](#metadata-extraction)
Enable `extract_metadata` to populate the `metadata` field with structured data parsed from the HTML `` and document body.
* Rust
```rust
use html_to_markdown_rs::{convert, ConversionOptions};
fn main() -> Result<(), Box> {
let html = r#"My Page
Hello Link "#;
let options = ConversionOptions::builder()
.extract_metadata(true)
.build();
let result = convert(html, Some(options))?;
let markdown = result.content.clone().unwrap_or_default();
println!("Markdown: {markdown}");
println!("Title: {:?}", result.metadata.document.title);
println!("Links: {:?}", result.metadata.links);
Ok(())
}
```
* Python
```python
from html_to_markdown import ConversionOptions, convert
html = """
My Page
Hello
"""
options = ConversionOptions(
extract_metadata=True,
extract_images=True,
)
result = convert(html, options)
markdown = result.content
metadata = result.metadata
print(metadata.document.title)
```
* TypeScript
```typescript
import { convert, ConversionOptions } from "@xberg-io/html-to-markdown";
const options: ConversionOptions = { extractMetadata: true };
const result = convert("Title Content
", options);
console.log(result.content); // Converted markdown
console.log(result.metadata?.document); // Document metadata (title, description, etc.)
console.log(result.metadata?.headers); // Header elements (h1-h6)
console.log(result.metadata?.links); // Extracted links
console.log(result.metadata?.images); // Extracted images
```
* Go
```go
package main
import (
"fmt"
"log"
htmltomarkdown "github.com/xberg-io/html-to-markdown/packages/go/v3"
)
func main() {
html := `My Page
Hello Link `
// extract_metadata defaults to true; nil options is enough.
result, err := htmltomarkdown.Convert(html, nil)
if err != nil {
log.Fatal(err)
}
if result.Content != nil {
fmt.Println("Markdown:", *result.Content)
}
if result.Metadata.Document.Title != nil {
fmt.Println("Title:", *result.Metadata.Document.Title)
}
for _, link := range result.Metadata.Links {
fmt.Printf("Link: %s (%s)\n", link.Href, link.Text)
}
}
```
* Ruby
```ruby
require 'html_to_markdown'
html = 'Test Hello '
result = HtmlToMarkdown.convert(html, extract_metadata: true)
markdown = result.content
puts result.metadata.document.title # "Test"
puts result.metadata.headers.first.text # "Hello"
```
* PHP
```php
use HtmlToMarkdown\HtmlToMarkdownApi;
$html = 'Example Welcome Link ';
// extract_metadata defaults to true.
$result = HtmlToMarkdownApi::convert($html);
echo $result->content;
echo $result->getMetadata()->getDocument()->title;
foreach ($result->getMetadata()->getLinks() as $link) {
echo $link->href . ': ' . $link->text;
}
```
* Java
```java
import io.xberg.htmltomarkdown.HtmlToMarkdown;
import io.xberg.htmltomarkdown.ConversionOptions;
import io.xberg.htmltomarkdown.ConversionResult;
import io.xberg.htmltomarkdown.HtmlToMarkdownRsException;
public class MetadataExample {
public static void main(String[] args) throws HtmlToMarkdownRsException {
String html = """
My Page
Hello Link
""";
ConversionOptions options = ConversionOptions.builder()
.withExtractMetadata(true)
.build();
ConversionResult result = HtmlToMarkdown.convert(html, options);
System.out.println("Markdown: " + result.content());
System.out.println("Title: " + result.metadata().document().title());
System.out.println("Links: " + result.metadata().links());
}
}
```
* C#
```csharp
using HtmlToMarkdown;
var html = @"My Page
Hello Link ";
var options = new ConversionOptions { ExtractMetadata = true };
var result = HtmlToMarkdownConverter.Convert(html, options);
Console.WriteLine($"Markdown: {result.Content}");
Console.WriteLine($"Title: {result.Metadata.Document.Title}");
Console.WriteLine($"Links: {string.Join(", ", result.Metadata.Links)}");
```
* Elixir
# Metadata Extraction - Elixir
Extract structured metadata from HTML documents during conversion.
## Basic Metadata Extraction
Use `convert/2` with `extract_metadata: true` in options to extract document metadata alongside Markdown:
```elixir
html = """
Example
Welcome
Example link
"""
opts = %HtmlToMarkdown.ConversionOptions{extract_metadata: true}
{:ok, result} = HtmlToMarkdown.convert(html, opts)
IO.inspect(result.metadata.document.title) # "Example"
IO.inspect(result.metadata.headers |> hd() |> Map.get(:text)) # "Welcome"
IO.inspect(result.metadata.links |> hd() |> Map.get(:link_type)) # :external
```
## Extracted Metadata Structure
The metadata map includes:
* **Document**: Title and meta tags from ``
* **Headers**: All headings extracted with level, text, and optional ID
* **Links**: All links with href, text, rel attributes, and link_type classification
* **Images**: Image sources and alt text
* **Forms**: Form action and method data
* **Other**: Tables, code blocks, and additional structural information
* R
```r
library(htmltomarkdown)
html <- '
Example
Welcome
Example link
'
opts <- conversion_options(extract_metadata = TRUE)
result <- convert(html, opts)
cat(result$content)
result$metadata$document$title
result$metadata$headers[[1]]$text
result$metadata$links[[1]]$link_type
```
* C
```c
#include "html_to_markdown.h"
#include
int main(void) {
const char *html =
"Page Hello ";
/* extract_metadata is true by default. */
HTMAlefHandle result = htm_convert(html, 0);
if (result == 0) {
fprintf(stderr, "convert failed: %s\n", htm_last_error_context());
return 1;
}
HTMAlefHandle meta = htm_conversion_result_metadata(result);
if (meta != 0) {
HTMAlefHandle doc = htm_html_metadata_document(meta);
char *title = htm_document_metadata_title(doc);
if (title != NULL) {
printf("Title: %s\n", title);
htm_free_string(title);
}
htm_document_metadata_free(doc);
htm_html_metadata_free(meta);
}
htm_conversion_result_free(result);
return 0;
}
```
* WASM
```javascript
import { convert, WasmConversionOptions } from "@xberg-io/html-to-markdown-wasm";
const html =
'My Page Hello Link ';
const options = WasmConversionOptions.default();
options.extractMetadata = true;
const result = convert(html, options);
console.log("Markdown:", result.content);
console.log("Title:", result.metadata.document.title);
console.log(
"Links:",
result.metadata.links.map((link) => link.href),
);
```
* Swift
```swift
import HtmlToMarkdown
let options = try conversionOptionsFromJson(
"{\"extract_metadata\":true,\"extract_images\":true}"
)
let html = """
My Page
Welcome
See example .
"""
let result = try convert(html: html, options: options)
let markdown = result.content ?? ""
let metadata = result.metadata
let document = metadata.document
print("title:", document.title ?? "")
print("description:", document.description ?? "")
print("author:", document.author ?? "")
print("headers:", metadata.headers.count)
print("links:", metadata.links.count)
print("images:", metadata.images.count)
print(markdown)
```
* Dart
```dart
import 'package:h2m/h2m.dart';
import 'package:h2m/src/html_to_markdown_rs_bridge_generated/frb_generated.dart'
show RustLib;
Future main() async {
await RustLib.init();
final options = await createConversionOptionsFromJson(
json: '{"extract_metadata":true}',
);
final result = await H2mBridge.convert(
'Example '
'Hello link ',
options: options,
);
print(result.content);
print(result.metadata.document.title); // "Example"
print(result.metadata.document.description); // "A sample page"
print(result.metadata.headers); // List
print(result.metadata.links); // List
print(result.metadata.images); // List
}
```
* Kotlin Android
```kotlin
import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.databind.PropertyNamingStrategies
import com.fasterxml.jackson.module.kotlin.registerKotlinModule
import io.xberg.android.ConversionOptions
import io.xberg.android.HtmlToMarkdown
fun main() {
val mapper = ObjectMapper()
.registerKotlinModule()
.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE)
val options = mapper.readValue(
"{\"extract_metadata\":true}",
ConversionOptions::class.java,
)
val html = """
My Page
Hello Link
""".trimIndent()
val result = HtmlToMarkdown.convert(html, options)
println("Markdown: ${result.content}")
println("Title: ${result.metadata.document.title}")
println("Description: ${result.metadata.document.description}")
println("Headers: ${result.metadata.headers}")
println("Links: ${result.metadata.links}")
println("Images: ${result.metadata.images}")
}
```
* Zig
```zig
const std = @import("std");
const html_to_markdown = @import("html_to_markdown_rs");
pub fn main() !void {
var gpa: std.heap.DebugAllocator(.{}) = .init;
defer _ = gpa.deinit();
const allocator = gpa.allocator();
const html =
\\
\\Example Page
\\Hello
;
// `convert` returns the ConversionResult as a JSON string. Metadata
// extraction is controlled by the `extract_metadata` option (default true).
const result_json = try html_to_markdown.convert(html, "{\"extract_metadata\":true}");
defer std.heap.c_allocator.free(result_json);
var parsed = try std.json.parseFromSlice(std.json.Value, allocator, result_json, .{});
defer parsed.deinit();
const document = parsed.value.object.get("metadata").?.object.get("document").?.object;
if (document.get("title")) |v| {
if (v == .string) std.debug.print("Title: {s}\n", .{v.string});
}
if (document.get("description")) |v| {
if (v == .string) std.debug.print("Description: {s}\n", .{v.string});
}
if (document.get("author")) |v| {
if (v == .string) std.debug.print("Author: {s}\n", .{v.string});
}
if (document.get("canonical_url")) |v| {
if (v == .string) std.debug.print("Canonical: {s}\n", .{v.string});
}
}
```
### Metadata Fields
[Section titled “Metadata Fields”](#metadata-fields)
`result.metadata` is an `HtmlMetadata` with five top-level fields: `document`, `headers`, `links`, `images`, and `structured_data`. Everything is populated in a single pass.
#### `document` (DocumentMetadata)
[Section titled “document (DocumentMetadata)”](#document-documentmetadata)
| Field | Type | Description |
| ---------------- | -------------------------- | ----------------------------------------------------------------------------- |
| `title` | `Option` | Page title from the `` element. |
| `description` | `Option<String>` | `<meta name="description">` content. |
| `keywords` | `Vec<String>` | Parsed `<meta name="keywords">`, split on commas. |
| `author` | `Option<String>` | `<meta name="author">` content. |
| `canonical_url` | `Option<String>` | `<link rel="canonical">` href. |
| `base_href` | `Option<String>` | `<base href="…">` value. |
| `language` | `Option<String>` | `lang` attribute on `<html>`. |
| `text_direction` | `Option<TextDirection>` | `dir` attribute on `<html>`. One of `left_to_right`, `right_to_left`, `auto`. |
| `open_graph` | `BTreeMap<String, String>` | All `og:*` meta tags keyed by property (without the `og:` prefix). |
| `twitter_card` | `BTreeMap<String, String>` | All `twitter:*` meta tags keyed by name (without the prefix). |
| `meta_tags` | `BTreeMap<String, String>` | Every other `<meta name>` tag, keyed by name. |
#### `headers`, `links`, `images`, `structured_data`
[Section titled “headers, links, images, structured_data”](#headers-links-images-structured_data)
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| `headers` | `HeaderMetadata` entries for every `<h1>`–`<h6>` with level, text, and id. |
| `links` | `LinkMetadata` entries for every `<a>` with href, text, `rel` values, and classified `link_type`. |
| `images` | `ImageMetadata` entries for every `<img>` with src, alt, dimensions, and classified `image_type`. |
| `structured_data` | JSON-LD, Microdata, and RDFa blocks with a `data_type` tag and the raw content. |
#### `links[].link_type`
[Section titled “links\[\].link_type”](#linkslink_type)
| Value | Matches |
| ---------- | ------------------------------------------------------------------- |
| `anchor` | href starts with `#` (same-page anchors). |
| `internal` | relative href or href that resolves inside the document’s own host. |
| `external` | absolute URL on a different host. |
| `email` | `mailto:` URI. |
| `phone` | `tel:` URI. |
| `other` | anything else (`javascript:`, `data:`, custom schemes). |
#### `images[].image_type`
[Section titled “images\[\].image_type”](#imagesimage_type)
| Value | Matches |
| ------------ | ------------------------------------------------------------------- |
| `data_uri` | `src` starts with `data:`. |
| `inline_svg` | inline `<svg>` element (captured when `extract_images` is enabled). |
| `external` | absolute URL on a remote host. |
| `relative` | relative path or same-host URL. |
#### `structured_data[].data_type`
[Section titled “structured_data\[\].data_type”](#structured_datadata_type)
| Value | Matches |
| ----------- | --------------------------------------------- |
| `json_ld` | `<script type="application/ld+json">` blocks. |
| `microdata` | `itemscope`/`itemprop` subtrees. |
| `rdfa` | `typeof`/`property` subtrees. |
## Document Structure Extraction
[Section titled “Document Structure Extraction”](#document-structure-extraction)
Enable `include_document_structure` to get a parsed tree of the document’s structural elements.
* Rust
```rust
use html_to_markdown_rs::{convert, ConversionOptions};
let options = ConversionOptions::builder()
.include_document_structure(true)
.build();
let result = convert("<h1>Title</h1><p>Paragraph</p>", Some(options))?;
if let Some(doc) = &result.document {
for node in &doc.nodes {
println!("{:?}", node);
}
}
```
* Python
```python
from html_to_markdown import ConversionOptions, convert
options = ConversionOptions(include_document_structure=True)
result = convert("<h1>Title</h1><p>Paragraph</p>", options)
doc = result.document
for node in doc.nodes:
print(node)
```
* TypeScript
```typescript
import { convert, ConversionOptions } from '@xberg-io/html-to-markdown';
const options: ConversionOptions = { includeDocumentStructure: true };
const result = convert('<h1>Title</h1><p>Paragraph</p>', options);
const nodes = result.document?.nodes ?? [];
for (const node of nodes) {
console.log(node);
}
```
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.
# Visitor Pattern
The visitor system is the library’s main extensibility point. Implement `HtmlVisitor` and you can replace, skip, or augment how any HTML element becomes Markdown. No fork required.
Rust users must opt in with `features = ["visitor"]`. The Rust trait is `HtmlVisitor: Debug + Send`, and the public handle is `Arc<Mutex<dyn HtmlVisitor + Send>>`. Generated bindings expose visitors only where the backend supports trait handles; Kotlin Android excludes visitor support.
## Execution Order
[Section titled “Execution Order”](#execution-order)
Traversal is pre-order. For `<div><p>text</p></div>`:
1. `visit_element_start` fires for `<div>`
2. `visit_element_start` fires for `<p>`
3. `visit_text` fires for `"text"`
4. `visit_element_end` fires for `<p>` with the rendered output
5. `visit_element_end` fires for `<div>` with the rendered output
`visit_text` is hot. It runs for every text node in the document, often 100+ times on a single page. Return `Continue` fast when you don’t care about the node, and avoid allocations in the method body.
## VisitResult
[Section titled “VisitResult”](#visitresult)
Every callback returns a `VisitResult`.
| Variant | Effect |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Continue` | Use the default rendering. |
| `Custom(String)` | Replace the default output with the supplied Markdown. The visitor owns the rendering for this node and its children. |
| `Skip` | Drop the element and all of its children. |
| `PreserveHtml` | Emit the raw HTML for this element verbatim. |
| `Error(String)` | Halt conversion. The message surfaces as `ConversionError::Visitor` in Rust (behind `features = ["visitor"]`). |
## NodeContext
[Section titled “NodeContext”](#nodecontext)
Every callback receives a `NodeContext` describing the current node.
| Field | Type | Meaning |
| ----------------- | -------------------------- | ------------------------------------------------------------------------------------ |
| `node_type` | `NodeType` | Coarse-grained classification (heading, list, link, form, …). 87 variants. |
| `tag_name` | `String` | Raw HTML tag name. Lowercased. |
| `attributes` | `BTreeMap<String, String>` | All attributes on the element. |
| `depth` | `usize` | Depth in the DOM tree. Root is 0. |
| `index_in_parent` | `usize` | 0-based position among siblings. |
| `parent_tag` | `Option<String>` | Parent element’s tag, or `None` at the root. |
| `is_inline` | `bool` | `true` when the element is rendered inline (inside a paragraph, link text, cell, …). |
## Method Reference
[Section titled “Method Reference”](#method-reference)
All 40 methods have default implementations that return `Continue`. Override only the ones you care about.
### Generic element callbacks
[Section titled “Generic element callbacks”](#generic-element-callbacks)
| Method | When it fires |
| ------------------------------------------- | -------------------------------------------------- |
| `visit_element_start(ctx)` | Before any element. First callback for every node. |
| `visit_element_end(ctx, output)` | After an element, with the rendered Markdown. |
| `visit_text(ctx, text)` | Every text node. HTML entities already decoded. |
| `visit_custom_element(ctx, tag_name, html)` | Unknown tags and web components. |
### Links and images
[Section titled “Links and images”](#links-and-images)
| Method | Arguments |
| ------------------------------------ | ---------------------------------------------------------- |
| `visit_link(ctx, href, text, title)` | `<a>` anchor with href, rendered text, and optional title. |
| `visit_image(ctx, src, alt, title)` | `<img>` with src, alt text, and optional title. |
### Headings, rules, breaks
[Section titled “Headings, rules, breaks”](#headings-rules-breaks)
| Method | Arguments |
| ------------------------------------- | ------------------------------------------------------ |
| `visit_heading(ctx, level, text, id)` | `<h1>`–`<h6>` with level (1-6), text, and optional id. |
| `visit_horizontal_rule(ctx)` | `<hr>`. |
| `visit_line_break(ctx)` | `<br>`. |
### Code
[Section titled “Code”](#code)
| Method | Arguments |
| ----------------------------------- | --------------------------------------------- |
| `visit_code_block(ctx, lang, code)` | `<pre><code>` with language tag and raw code. |
| `visit_code_inline(ctx, code)` | Inline `<code>`. |
### Lists
[Section titled “Lists”](#lists)
| Method | Arguments |
| --------------------------------------------- | ------------------------------------------ |
| `visit_list_start(ctx, ordered)` | Before `<ul>` or `<ol>`. |
| `visit_list_item(ctx, ordered, marker, text)` | Each `<li>` with marker and rendered text. |
| `visit_list_end(ctx, ordered, output)` | After the list, with the rendered block. |
### Definition lists
[Section titled “Definition lists”](#definition-lists)
| Method | Arguments |
| ----------------------------------------- | -------------- |
| `visit_definition_list_start(ctx)` | Before `<dl>`. |
| `visit_definition_term(ctx, text)` | `<dt>`. |
| `visit_definition_description(ctx, text)` | `<dd>`. |
| `visit_definition_list_end(ctx, output)` | After `<dl>`. |
### Tables
[Section titled “Tables”](#tables)
| Method | Arguments |
| ---------------------------------------- | -------------------------------------------------------------------------------------------- |
| `visit_table_start(ctx)` | Before `<table>`. |
| `visit_table_row(ctx, cells, is_header)` | Each `<tr>`. Cells are pre-rendered Markdown. `is_header` is true for rows inside `<thead>`. |
| `visit_table_end(ctx, output)` | After `<table>`. |
### Blockquote
[Section titled “Blockquote”](#blockquote)
| Method | Arguments |
| --------------------------------------- | ------------------------------------------------------- |
| `visit_blockquote(ctx, content, depth)` | `<blockquote>` with rendered content and nesting depth. |
### Inline formatting
[Section titled “Inline formatting”](#inline-formatting)
| Method | Covers |
| -------------------------------- | --------------------------- |
| `visit_strong(ctx, text)` | `<strong>`, `<b>`. |
| `visit_emphasis(ctx, text)` | `<em>`, `<i>`. |
| `visit_strikethrough(ctx, text)` | `<s>`, `<del>`, `<strike>`. |
| `visit_underline(ctx, text)` | `<u>`, `<ins>`. |
| `visit_subscript(ctx, text)` | `<sub>`. |
| `visit_superscript(ctx, text)` | `<sup>`. |
| `visit_mark(ctx, text)` | `<mark>`. |
### Forms
[Section titled “Forms”](#forms)
| Method | Arguments |
| ------------------------------------------- | --------------------------------------------- |
| `visit_form(ctx, action, method)` | `<form>` with optional action URL and method. |
| `visit_input(ctx, input_type, name, value)` | `<input>`. |
| `visit_button(ctx, text)` | `<button>`. |
### Media
[Section titled “Media”](#media)
| Method | Arguments |
| ------------------------ | ----------- |
| `visit_audio(ctx, src)` | `<audio>`. |
| `visit_video(ctx, src)` | `<video>`. |
| `visit_iframe(ctx, src)` | `<iframe>`. |
### Interactive
[Section titled “Interactive”](#interactive)
| Method | Arguments |
| -------------------------- | -------------------------------------- |
| `visit_details(ctx, open)` | `<details>` with the `open` attribute. |
| `visit_summary(ctx, text)` | `<summary>`. |
### Figures
[Section titled “Figures”](#figures)
| Method | Arguments |
| ------------------------------- | ------------------ |
| `visit_figure_start(ctx)` | Before `<figure>`. |
| `visit_figcaption(ctx, text)` | `<figcaption>`. |
| `visit_figure_end(ctx, output)` | After `<figure>`. |
## Basic Visitor
[Section titled “Basic Visitor”](#basic-visitor)
* Rust
```rust
use html_to_markdown_rs::visitor::{HtmlVisitor, NodeContext, VisitResult, VisitorHandle};
use html_to_markdown_rs::{ConversionOptions, convert};
use std::sync::{Arc, Mutex};
#[derive(Debug)]
struct LinkRewriter;
impl HtmlVisitor for LinkRewriter {
fn visit_link(
&mut self,
_ctx: &NodeContext,
href: &str,
text: &str,
_title: Option<&str>,
) -> VisitResult {
VisitResult::Custom(format!("[{text}](https://track.example.com?url={href})"))
}
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let html = r#"<a href="https://example.com">Click here</a>"#;
let visitor: VisitorHandle = Arc::new(Mutex::new(LinkRewriter));
let options = ConversionOptions::builder().visitor(Some(visitor)).build();
let result = convert(html, Some(options))?;
println!("{}", result.content.unwrap_or_default());
Ok(())
}
```
* Python
```python
from html_to_markdown import ConversionOptions, convert
html = '<p>Visit <a href="https://example.com">our site</a>.</p>'
class CustomVisitor:
def visit_link(self, ctx, href, text, title):
return {"type": "continue"}
def visit_image(self, ctx, src, alt, title):
return {"type": "continue"}
options = ConversionOptions(visitor=CustomVisitor())
result = convert(html, options)
markdown = result.content
print(markdown)
```
* TypeScript
```typescript
import { convert, ConversionOptions, NodeContext, VisitResult } from "@xberg-io/html-to-markdown";
// `visitor` is a plain object of camelCase callbacks; there is no exported
// `Visitor` type to annotate it with. Return `VisitResult.Continue` / `Skip` /
// `PreserveHtml` for the built-in behaviors, or `{ Custom: "..." }` to replace
// the node's output with custom markdown.
const visitor = {
visitLink(ctx: NodeContext, href: string, text: string) {
// Custom handling for links
return { Custom: `[${text}](${href})` };
},
visitHeading(ctx: NodeContext, level: number, text: string): VisitResult {
// Fall back to the default handling for headings
return VisitResult.Continue;
},
};
const options: ConversionOptions = { visitor };
const result = convert('<h1>Title</h1><a href="url">Link</a>', options);
const markdown = result.content;
```
* Go
```go
// The visitor pattern is not yet supported in the Go binding.
// Use Convert() with ConversionOptions instead.
```
* Ruby
```ruby
require 'html_to_markdown'
# A visitor is any Ruby object that responds to `visit_*` methods. The
# bridge calls `respond_to?(name, false)` and dispatches via `funcall`,
# so plain methods on a class (or any object) work.
class MyVisitor
# `ctx` is a Hash: { node_type:, tag_name:, depth:, index_in_parent:, ... }
def visit_link(ctx, href, text, title = nil)
# Return a custom output by wrapping it in `{ Custom: ... }`. The key
# is matched case-sensitively, so it must be `:Custom` (not `:custom`).
{ Custom: "[#{text}](#{href})" }
end
def visit_image(ctx, src, alt, title = nil)
# Return :Skip to drop the element. The directive symbols/strings are
# matched case-sensitively: :Continue, :Skip, :PreserveHtml. Anything
# else (including :skip or "skip") is treated as literal custom output.
:Skip
end
# `visit_text` is invoked ~100+ times per document — keep it cheap.
def visit_text(ctx, text)
:Continue
end
end
html = "<p><a href='https://example.com'>Link</a><img src='x.png'></p>"
# The visitor is passed as the second positional argument. The Ruby
# binding currently does NOT support combining the visitor with a
# `ConversionOptions` Hash in a single call — pick one. To use both,
# build the options on the Rust side via the FFI directly.
result = HtmlToMarkdown.convert(html, MyVisitor.new)
puts result.content
```
* PHP
```php
use HtmlToMarkdown\HtmlToMarkdownApi;
use HtmlToMarkdown\ConversionOptions;
use HtmlToMarkdown\VisitorHandle;
// Visitors are duck-typed: define any subset of visit_* methods.
// Each method returns either 'Skip', ['Custom' => '...'], or null/'Continue'.
$visitor = new class {
public function visit_link($ctx, $href, $text, $title) {
return ['Custom' => "[{$text}]({$href})"];
}
public function visit_image($ctx, $src, $alt, $title) {
return 'Skip';
}
};
$visitorHandle = VisitorHandle::from_php_object($visitor);
$options = ConversionOptions::from_json('{}')->withVisitor($visitorHandle);
$result = HtmlToMarkdownApi::convert(
'<a href="/page">Link</a><img src="pic.png" alt="pic">',
$options
);
echo $result->content;
```
* Java
```java
// The visitor pattern is not yet supported in the Java binding.
// Use convert() with ConversionOptions instead.
```
* C#
```csharp
using HtmlToMarkdown;
var html = "<a href=\"https://old-cdn.com/file.pdf\">Download</a>";
var options = new ConversionOptions { Visitor = new MyVisitor() };
var result = HtmlToMarkdownConverter.Convert(html, options);
Console.WriteLine(result.Content);
public sealed class MyVisitor : IHtmlVisitor
{
public VisitResult VisitLink(NodeContext ctx, string href, string text, string title)
{
// Rewrite CDN URLs.
if (href.StartsWith("https://old-cdn.com"))
{
href = href.Replace("https://old-cdn.com", "https://new-cdn.com");
}
return new VisitResult.Custom($"[{text}]({href})");
}
public VisitResult VisitImage(NodeContext ctx, string src, string alt, string title) =>
src.Contains("tracking") ? new VisitResult.Skip() : new VisitResult.Continue();
public VisitResult VisitText(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitElementStart(NodeContext ctx) => new VisitResult.Continue();
public VisitResult VisitElementEnd(NodeContext ctx, string output) => new VisitResult.Continue();
public VisitResult VisitHeading(NodeContext ctx, uint level, string text, string id) => new VisitResult.Continue();
public VisitResult VisitCodeBlock(NodeContext ctx, string lang, string code) => new VisitResult.Continue();
public VisitResult VisitCodeInline(NodeContext ctx, string code) => new VisitResult.Continue();
public VisitResult VisitListItem(NodeContext ctx, bool ordered, string marker, string text) => new VisitResult.Continue();
public VisitResult VisitListStart(NodeContext ctx, bool ordered) => new VisitResult.Continue();
public VisitResult VisitListEnd(NodeContext ctx, bool ordered, string output) => new VisitResult.Continue();
public VisitResult VisitTableStart(NodeContext ctx) => new VisitResult.Continue();
public VisitResult VisitTableRow(NodeContext ctx, List<string> cells, bool isHeader) => new VisitResult.Continue();
public VisitResult VisitTableEnd(NodeContext ctx, string output) => new VisitResult.Continue();
public VisitResult VisitBlockquote(NodeContext ctx, string content, ulong depth) => new VisitResult.Continue();
public VisitResult VisitStrong(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitEmphasis(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitStrikethrough(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitUnderline(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitSubscript(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitSuperscript(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitMark(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitLineBreak(NodeContext ctx) => new VisitResult.Continue();
public VisitResult VisitHorizontalRule(NodeContext ctx) => new VisitResult.Continue();
public VisitResult VisitCustomElement(NodeContext ctx, string tagName, string html) => new VisitResult.Continue();
public VisitResult VisitDefinitionListStart(NodeContext ctx) => new VisitResult.Continue();
public VisitResult VisitDefinitionTerm(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitDefinitionDescription(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitDefinitionListEnd(NodeContext ctx, string output) => new VisitResult.Continue();
public VisitResult VisitForm(NodeContext ctx, string action, string method) => new VisitResult.Continue();
public VisitResult VisitInput(NodeContext ctx, string inputType, string name, string value) => new VisitResult.Continue();
public VisitResult VisitButton(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitAudio(NodeContext ctx, string src) => new VisitResult.Continue();
public VisitResult VisitVideo(NodeContext ctx, string src) => new VisitResult.Continue();
public VisitResult VisitIframe(NodeContext ctx, string src) => new VisitResult.Continue();
public VisitResult VisitDetails(NodeContext ctx, bool open) => new VisitResult.Continue();
public VisitResult VisitSummary(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitFigureStart(NodeContext ctx) => new VisitResult.Continue();
public VisitResult VisitFigcaption(NodeContext ctx, string text) => new VisitResult.Continue();
public VisitResult VisitFigureEnd(NodeContext ctx, string output) => new VisitResult.Continue();
}
```
* Elixir
# Visitor Pattern - Elixir
Customize HTML to Markdown conversion by passing a visitor map under the `:visitor` key of `HtmlToMarkdown.convert/2`’s options. Each entry maps a callback **atom** (e.g. `:handle_link`) to a one-arity function that receives a native, string-keyed arguments map built on the Rust side.
The bridge spawns a system thread for the conversion, then sends `{:visitor_callback, ref_id, callback_name, args_json}` messages back to the calling process. `HtmlToMarkdown.convert/2` runs a receive loop that dispatches each message against your visitor map and calls `HtmlToMarkdown.Native.visitor_reply/2` to unblock the worker.
## Basic Visitor Example
```elixir
visitor = %{
:handle_link => fn args ->
text = Map.get(args, "text", "")
{:custom, text}
end,
:handle_image => fn _args -> :skip end,
:handle_text => fn _args -> :continue end
}
html = "<p>Visit <a href='https://example.com'>our site</a> for more!</p>"
{:ok, result} = HtmlToMarkdown.convert(html, %{visitor: visitor})
IO.puts(result.content)
# => Visit our site for more!
```
## Visitor Return Values
Each function must return one of:
* `:continue` — proceed with default conversion
* `:skip` — omit this element entirely
* `:preserve_html` — include the raw HTML verbatim
* `{:custom, markdown_string}` — replace this element’s output with the given string
* A bare string — treated as a custom replacement
Anything else falls back to `:continue`.
## Callback Names
Callbacks are keyed by atom and use the `handle_` prefix (the bridge translates the Rust `visit_X` trait methods to `:handle_X` over the wire). Frequently overridden:
* `:handle_text` — text nodes: `%{"ctx" => …, "text" => "…"}` (called \~100+ times per document; keep it cheap)
* `:handle_link` — `<a>` elements: `%{"ctx" => …, "href" => "…", "text" => "…", "title" => …}`
* `:handle_image` — `<img>` elements: `%{"ctx" => …, "src" => "…", "alt" => "…", "title" => …}`
* `:handle_heading` — headings: `%{"ctx" => …, "level" => 1, "text" => "…", "id" => …}`
* `:handle_code_block` — `<pre><code>`: `%{"ctx" => …, "lang" => …, "code" => "…"}`
* `:handle_element_start` / `:handle_element_end` — generic enter/leave hooks
Omit a callback to fall through to the default Rust implementation.
## Node Context
The `"ctx"` value in every callback arg map is a `%HtmlToMarkdown.NodeContext{}` struct:
```elixir
%HtmlToMarkdown.NodeContext{
node_type: :link,
tag_name: "a",
depth: 2,
index_in_parent: 0,
parent_tag: "p",
is_inline: true
}
```
## Combining Options and Visitor
Pass the visitor under the `:visitor` key alongside any other `ConversionOptions` fields:
```elixir
{:ok, result} = HtmlToMarkdown.convert(html, %{
visitor: %{:handle_link => fn _ -> :skip end},
output_format: "github",
extract_metadata: true
})
```
`HtmlToMarkdown.convert/2` pops the `:visitor` key, JSON-encodes the remaining options, and dispatches to `convert_with_visitor`.
* R
```r
library(htmltomarkdown)
html <- "<p>Visit <a href='https://example.com'>our site</a> for more!</p>"
opts <- conversion_options(extract_metadata = FALSE)
result <- convert(html, opts)
cat(result$content)
```
* C
```c
#include "html_to_markdown.h"
#include <stdio.h>
/* Each callback returns an int32 status code:
* HTMHTM_VISIT_CONTINUE — use default conversion
* HTMHTM_VISIT_SKIP — drop the element
* HTMHTM_VISIT_PRESERVE_HTML — emit the raw HTML
* HTMHTM_VISIT_CUSTOM — replace with the string written to *out_custom
* HTMHTM_VISIT_ERROR — abort conversion with the error in *out_custom
*/
static int32_t visit_heading(const struct HTMHtmContext *ctx,
void *user_data,
uint32_t level,
const char *text,
const char *id,
char **out_custom,
uintptr_t *out_len) {
(void)ctx; (void)user_data; (void)level; (void)text; (void)id; (void)out_custom; (void)out_len;
return HTMHTM_VISIT_CONTINUE;
}
int main(void) {
HTMHtmVisitorCallbacks callbacks = {0};
callbacks.visit_heading = visit_heading;
HTMAlefHandle visitor = htm_visitor_create(&callbacks);
HTMAlefHandle options = htm_conversion_options_default();
htm_options_set_visitor(options, visitor);
HTMAlefHandle result = htm_convert("<h1>Title</h1><p>Content</p>", options);
htm_conversion_options_free(options);
htm_visitor_free(visitor);
if (result == 0) {
fprintf(stderr, "convert failed: %s\n", htm_last_error_context());
return 1;
}
char *content = htm_conversion_result_content(result);
if (content != NULL) {
printf("%s\n", content);
htm_free_string(content);
}
htm_conversion_result_free(result);
return 0;
}
```
* WASM
```typescript
import { convert, WasmConversionOptions, WasmNodeContext, WasmVisitorHandle } from "@xberg-io/html-to-markdown-wasm";
const visitor = {
visitLink(ctx: WasmNodeContext, href: string, text: string, title: string) {
return { Custom: `[${text}](${href} "external")` };
},
};
const options = WasmConversionOptions.default();
options.visitor = new WasmVisitorHandle(visitor);
const result = convert('<h1>Hello</h1><a href="https://example.com">link</a>', options);
console.log(result.content);
```
* Swift
```swift
import HtmlToMarkdown
final class CustomVisitor: HtmlVisitorProtocol {
func visitLink(_ ctx: NodeContext, _ href: String, _ text: String, _ title: String?) -> VisitResult {
// Replace links with a bracketed custom format
return .custom(field0: "[\(text)](\(href))")
}
func visitHeading(_ ctx: NodeContext, _ level: UInt32, _ text: String, _ id: String?) -> VisitResult {
// Keep default rendering for headings
return .continue
}
}
let visitorHandle = makeHtmlVisitorHandle(CustomVisitor())
let options = try conversionOptionsFromJsonWithVisitor("{}", visitorHandle)
let html = "<h1>Title</h1><p>See <a href=\"https://example.com\">example</a>.</p>"
let result = try convert(html: html, options: options)
let markdown = result.content ?? ""
print(markdown)
```
* Dart
```dart
import 'dart:io';
import 'package:h2m/h2m.dart';
import 'package:h2m/src/html_to_markdown_rs_bridge_generated/frb_generated.dart'
show RustLib;
Future<void> main() async {
await RustLib.init();
// flutter_rust_bridge requires every visit callback — default to continue_()
// and override only the hooks you care about (here: links and headings).
final visitor = await createHtmlVisitor(
visitText: (ctx, text) async => VisitResult.continue_(),
visitElementStart: (ctx) async => VisitResult.continue_(),
visitElementEnd: (ctx, output) async => VisitResult.continue_(),
visitLink: (ctx, href, text, title) async =>
VisitResult.custom(field0: '[$text]($href)'),
visitImage: (ctx, src, alt, title) async => VisitResult.continue_(),
visitHeading: (ctx, level, text, id) async =>
VisitResult.custom(field0: '${'#' * level.toInt()} $text\n'),
visitCodeBlock: (ctx, lang, code) async => VisitResult.continue_(),
visitCodeInline: (ctx, code) async => VisitResult.continue_(),
visitListItem: (ctx, ordered, marker, text) async => VisitResult.continue_(),
visitListStart: (ctx, ordered) async => VisitResult.continue_(),
visitListEnd: (ctx, ordered, output) async => VisitResult.continue_(),
visitTableStart: (ctx) async => VisitResult.continue_(),
visitTableRow: (ctx, cells, isHeader) async => VisitResult.continue_(),
visitTableEnd: (ctx, output) async => VisitResult.continue_(),
visitBlockquote: (ctx, content, depth) async => VisitResult.continue_(),
visitStrong: (ctx, text) async => VisitResult.continue_(),
visitEmphasis: (ctx, text) async => VisitResult.continue_(),
visitStrikethrough: (ctx, text) async => VisitResult.continue_(),
visitUnderline: (ctx, text) async => VisitResult.continue_(),
visitSubscript: (ctx, text) async => VisitResult.continue_(),
visitSuperscript: (ctx, text) async => VisitResult.continue_(),
visitMark: (ctx, text) async => VisitResult.continue_(),
visitLineBreak: (ctx) async => VisitResult.continue_(),
visitHorizontalRule: (ctx) async => VisitResult.continue_(),
visitCustomElement: (ctx, tagName, html) async => VisitResult.continue_(),
visitDefinitionListStart: (ctx) async => VisitResult.continue_(),
visitDefinitionTerm: (ctx, text) async => VisitResult.continue_(),
visitDefinitionDescription: (ctx, text) async => VisitResult.continue_(),
visitDefinitionListEnd: (ctx, output) async => VisitResult.continue_(),
visitForm: (ctx, action, method) async => VisitResult.continue_(),
visitInput: (ctx, inputType, name, value) async => VisitResult.continue_(),
visitButton: (ctx, text) async => VisitResult.continue_(),
visitAudio: (ctx, src) async => VisitResult.continue_(),
visitVideo: (ctx, src) async => VisitResult.continue_(),
visitIframe: (ctx, src) async => VisitResult.continue_(),
visitDetails: (ctx, open) async => VisitResult.continue_(),
visitSummary: (ctx, text) async => VisitResult.continue_(),
visitFigureStart: (ctx) async => VisitResult.continue_(),
visitFigcaption: (ctx, text) async => VisitResult.continue_(),
visitFigureEnd: (ctx, output) async => VisitResult.continue_(),
);
final options = await createConversionOptionsFromJsonWithVisitor(
json: '{}',
visitor: visitor,
);
final result = await H2mBridge.convert(
'<h1>Title</h1><a href="https://example.com">Link</a>',
options: options,
);
print(result.content);
// The visitor callback keeps a native SendPort alive, which would
// otherwise hold the process open indefinitely.
exit(0);
}
```
* Kotlin Android
```kotlin
// The visitor pattern is not yet supported in the Kotlin Android binding.
// Use HtmlToMarkdown.convert() with ConversionOptions instead — for example,
// configure exclude_selectors, strip_tags, or preserve_tags to control output.
```
* Zig
```zig
const std = @import("std");
const html_to_markdown = @import("html_to_markdown_rs");
const c = html_to_markdown.c;
// Visitor callbacks return an int32 status code:
// 0 (HTM_VISIT_CONTINUE) use default conversion
// 1 (HTM_VISIT_CUSTOM) replace with the string written via out_custom/out_len
// 2 (HTM_VISIT_SKIP) drop the element
// 3 (HTM_VISIT_PRESERVE_HTML) emit the raw HTML
// 4 (HTM_VISIT_ERROR) abort conversion with the error in out_custom
fn visit_heading(
_ctx: [*c]const c.HTMHtmContext,
_user_data: ?*anyopaque,
_level: u32,
_text: [*c]const u8,
_id: [*c]const u8,
out_custom: [*c][*c]u8,
out_len: [*c]usize,
) callconv(.c) i32 {
_ = _ctx;
_ = _user_data;
_ = _id;
const text = std.mem.span(_text);
const buf = std.fmt.allocPrintSentinel(
std.heap.c_allocator,
"<<H{d}: {s}>>",
.{ _level, text },
0,
) catch return 0;
if (out_custom != null) out_custom.* = buf.ptr;
if (out_len != null) out_len.* = buf.len;
return 1; // HTM_VISIT_CUSTOM
}
pub fn main() !void {
var gpa: std.heap.DebugAllocator(.{}) = .init;
defer _ = gpa.deinit();
const allocator = gpa.allocator();
var callbacks: c.HTMHtmVisitorCallbacks = std.mem.zeroes(c.HTMHtmVisitorCallbacks);
callbacks.visit_heading = &visit_heading;
const visitor = c.htm_visitor_create(&callbacks);
defer c.htm_visitor_free(visitor);
const options_z = try std.heap.c_allocator.dupeZ(u8, "{}");
defer std.heap.c_allocator.free(options_z);
const options = c.htm_conversion_options_from_json(options_z.ptr);
defer c.htm_conversion_options_free(options);
c.htm_options_set_visitor(options, visitor);
const html_z = try std.heap.c_allocator.dupeZ(u8, "<h1>Title</h1><p>Body.</p>");
defer std.heap.c_allocator.free(html_z);
const result = c.htm_convert(html_z.ptr, options);
if (result == 0) return error.ConvertFailed;
defer c.htm_conversion_result_free(result);
const json_ptr = c.htm_conversion_result_to_json(result);
defer c.htm_free_string(json_ptr);
const json = std.mem.sliceTo(json_ptr, 0);
var parsed = try std.json.parseFromSlice(std.json.Value, allocator, json, .{});
defer parsed.deinit();
std.debug.print("{s}\n", .{parsed.value.object.get("content").?.string});
}
```
## Common Patterns
[Section titled “Common Patterns”](#common-patterns)
### Link rewriting
[Section titled “Link rewriting”](#link-rewriting)
Override `visit_link`, return `VisitResult::Custom(...)` with the new URL baked in. Useful for rewriting relative links to absolute, stripping tracking parameters, or converting internal links to anchor references.
### Element filtering
[Section titled “Element filtering”](#element-filtering)
Override `visit_element_start` and return `VisitResult::Skip` when `ctx.tag_name` matches an unwanted tag. The element and every descendant is dropped. A class filter works too: check `ctx.attributes.get("class")` and skip on match.
### Content extraction
[Section titled “Content extraction”](#content-extraction)
Override `visit_text` and push each text fragment into an external buffer. The visitor becomes a simple text-extraction pass that bypasses Markdown rendering. Combine with `Skip` on unwanted elements to exclude code blocks, navigation, or footers.
## Performance
[Section titled “Performance”](#performance)
`visit_text` fires on every text node. Keep the handler small. Match the few element kinds you care about in `visit_element_start` and return `Continue` for everything else. Allocations inside the handler multiply by the number of text nodes in the input.
The visitor trait is synchronous. The core walker calls each method in place during the single-pass DOM traversal.
Found a bug or mistake on this page?
If something here is wrong or out of date, [open an issue](https://github.com/xberg-io/html-to-markdown/issues/new?labels=documentation) on GitHub or [contribute a fix](https://github.com/xberg-io/html-to-markdown/blob/main/CONTRIBUTING.md) via pull request.