html-to-markdown
html-to-markdown is a high-performance HTML→Markdown converter with a Rust core and 12 native language bindings. It converts HTML to CommonMark Markdown, Djot, or plain text in a single pass, optionally extracting metadata, tables, inline images, and a structured document tree.
Use this skill when writing code that:
- Converts HTML strings, files, or live URLs to Markdown, Djot, or plain text
- Extracts metadata (title, OG tags, JSON-LD/Microdata/RDFa, headers, links, images, language) from HTML
- Extracts structured table data (GFM markdown + cell grids) from HTML
- Extracts a structured document-structure tree
- Extracts inline images (data URIs, SVGs) from HTML
- Uses preprocessing to clean noisy HTML (ads, navigation, forms) before conversion
Capability map
| Capability |
CLI |
SDKs |
| HTML→Markdown / Djot / plain text |
html-to-markdown FILE |
convert(html, options) |
| Read HTML from stdin / file / URL |
cat f | …, FILE, --url URL |
convert(htmlString, …) |
| ~30 config options (headings, code blocks, lists, escaping, wrapping…) |
flags |
ConversionOptions |
| Metadata extraction |
--json (default-extracted) |
result.metadata |
| Table extraction |
--json → tables[] |
result.tables |
| Document structure tree |
--json --include-structure |
include_document_structure=true |
| Inline image extraction |
--json --extract-inline-images |
extract_images=true |
| HTML preprocessing |
--preprocess [--preset …] |
PreprocessingOptions |
| Extraction-only (no Markdown body) |
--json --no-content |
options + read fields |
Installation
CLI
# (Homebrew 6.0+ requires explicit trust for third-party taps)
brew trust xberg-io/tap
brew install xberg-io/tap/html-to-markdown
# or run without a persistent install (the CLI proxy package self-installs the binary):
npx @xberg-io/html-to-markdown-cli --help
uvx --from html-to-markdown-cli html-to-markdown --help
# or download a prebuilt binary from the latest GitHub release:
# https://github.com/xberg-io/html-to-markdown/releases/latest
# or build from source:
cargo install html-to-markdown-cli
Language SDKs
pip install html-to-markdown # Python
npm install @xberg-io/html-to-markdown # TypeScript / Node.js
cargo add html-to-markdown-rs # Rust (features: metadata default; full = all)
gem install html-to-markdown # Ruby
composer require xberg-io/html-to-markdown # PHP
go get github.com/xberg-io/html-to-markdown/packages/go/v3 # Go
dotnet add package XbergIo.HtmlToMarkdown # C#
npm install @xberg-io/html-to-markdown-wasm # WASM
- Java (Maven):
io.xberg:html-to-markdown
- Elixir:
{:html_to_markdown, "~> 3.8"} in mix.exs
- R:
install.packages("htmltomarkdown", repos = "https://xberg-io.r-universe.dev")
- C (FFI): pre-built
.so / .dll / .dylib from GitHub releases
CLI vs SDK — which to use
- CLI — one-shot conversions, shell pipelines, fetching a single URL, ad-hoc metadata/table extraction via
--json | jq. Flags only for conversion (FILE is positional; omit or use - for stdin); the only subcommand is mcp.
- SDK — embedding conversion in application code, batch processing, custom element conversion (visitor pattern, Rust), and tight loops where process spawn overhead matters.
- MCP server —
html-to-markdown mcp exposes convert_html and extract_metadata as agent tools, so an MCP client can convert an HTML string directly with no shell-out. This plugin auto-registers it; see the using-the-mcp-server skill.
Both share the same ConversionResult shape, so output is interchangeable.
When to use html-to-markdown vs xberg vs crawlberg
- html-to-markdown — you already have HTML (a string, a file, or a single URL) and want clean Markdown plus structured metadata/tables. No OCR, no document parsing, no crawling.
- xberg — you have documents (PDF, Office, images, email, archives) and need full text/table/metadata extraction with optional OCR. Use it when the input is not already HTML.
- crawlberg — you need to crawl or scrape many pages, follow links, and handle JS-rendered sites with a headless-Chrome fallback. It uses html-to-markdown internally for the HTML→Markdown step.
Rule of thumb: single HTML in → Markdown out = html-to-markdown. Many URLs / a site = crawlberg. Non-HTML documents = xberg.
CLI quick start
# Convert a file to stdout
html-to-markdown input.html
# Convert and save
html-to-markdown input.html -o output.md
# Read from stdin
cat page.html | html-to-markdown
# Fetch and convert a URL
html-to-markdown --url https://example.com > out.md
# Full ConversionResult as JSON (content, tables, metadata, images, warnings)
html-to-markdown --json input.html
# JSON with document structure tree
html-to-markdown --json --include-structure input.html
# Extraction-only (no Markdown body)
html-to-markdown --json --no-content input.html
# Aggressive web-page cleanup
html-to-markdown input.html --preprocess --preset aggressive
SDK quick start
Rust
use html_to_markdown_rs::convert;
let result = convert("<h1>Hello World</h1><p>A paragraph.</p>", None)?;
println!("{}", result.content.unwrap_or_default());
Python
from html_to_markdown import convert
result = convert("<h1>Hello World</h1><p>A paragraph.</p>")
print(result.content) # # Hello World\n\nA paragraph.
print(result.metadata) # title, links, headers, …
TypeScript / Node.js
import { convert } from "@xberg-io/html-to-markdown";
// Node's convert() returns a ConversionResult object directly.
const result = convert("<h1>Hello World</h1><p>A paragraph.</p>");
console.log(result.content);
ConversionResult fields
All languages return the same structure (dict, object, or struct).
| Field |
Description |
content |
Converted text (Markdown/Djot/plain). null only in extraction-only mode. |
metadata |
Title, OG, headers, links, images, structured data. |
tables |
Tables with grid (structured cells) and markdown fields. |
images |
Extracted inline images (requires inline-image extraction). |
document |
Structured document tree when structure extraction is enabled. |
warnings |
Non-fatal processing warnings (message, kind). |
Configuration
All languages expose the same ~30 options. See references/configuration.md for the complete table. Common ones:
| Option |
Values |
Default |
heading_style |
atx, underlined, atx-closed |
atx |
code_block_style |
backticks, indented, tildes |
backticks |
output_format |
markdown, djot, plain |
markdown |
wrap / wrap_width |
bool / 20–500 |
off / 80 |
autolinks (SDK) / --no-autolinks (CLI) |
bool / flag |
true (on); disable in CLI with --no-autolinks |
| preprocessing |
minimal / standard / aggressive |
off |
Rust (builder)
use html_to_markdown_rs::{convert, ConversionOptions, HeadingStyle, OutputFormat};
let options = ConversionOptions::builder()
.heading_style(HeadingStyle::Atx)
.output_format(OutputFormat::Markdown)
.wrap(true)
.wrap_width(100)
.build();
let result = convert(html, Some(options))?;
Python (dataclass)
from html_to_markdown import convert, ConversionOptions, PreprocessingOptions
result = convert(
html,
ConversionOptions(heading_style="atx", wrap=True, wrap_width=100),
PreprocessingOptions(enabled=True, preset="aggressive"),
)
Metadata extraction
Metadata is extracted by default; in the CLI it appears under metadata in --json output. Fields include document (title, description, language, charset, open_graph), headers, links (with link_type), images, and structured_data (JSON-LD/Microdata/RDFa). See the extracting-metadata skill for details.
Table extraction
Tables appear in result.tables, each with a pre-rendered markdown string and a structured cell grid. Markdown tables also appear inline in content. See the extracting-tables skill.
Document structure extraction
Enable structure extraction (--include-structure on the CLI, include_document_structure=true in SDKs) to get a semantic node tree under document. Node types include heading, paragraph, list, list_item, table, image, code, quote, group, metadata_block.
Common pitfalls
convert() returns a result object, not a string. Access .content for the Markdown text. This holds for Node.js too — convert() returns a ConversionResult object directly; do not JSON.parse() it.
--json outputs JSON, not Markdown. Omit --json for plain Markdown.
--include-structure, --extract-inline-images, and --no-content require --json.
- The conversion CLI is flags-only.
FILE is positional; the only subcommand is mcp (starts the MCP server).
--preset, --keep-navigation, --keep-forms require --preprocess.
Additional resources
- CLI Reference — every flag, JSON shape, exit codes
- Configuration Reference — all 30+ options with defaults
- Rust API Reference — signatures, builder, feature flags
- Python API Reference — functions, dataclasses, type hints
- TypeScript API Reference — functions, interfaces, Buffer support
- Other Bindings — Go, Ruby, PHP, Java, C#, Elixir, R, WASM, C FFI
GitHub: https://github.com/xberg-io/html-to-markdown
1---2name: html-to-markdown3description: >-4 Convert HTML to Markdown, Djot, or plain text with structured extraction.5 Use when writing code that calls html-to-markdown APIs in Rust, Python,6 TypeScript, Go, Ruby, PHP, Java, C#, Elixir, R, C, or WASM.7 Covers installation, conversion, configuration, metadata extraction,8 tables, document structure, inline images, URL fetching, and CLI usage.9license: MIT10metadata:11 source: https://skillmd.com/skills/kreuzberg-dev/html-to-markdown12 author: xberg-io13 version: "0.1.0"14 repository: https://github.com/xberg-io/html-to-markdown15---1617<!--18AI-RULEZ :: GENERATED FILE — DO NOT EDIT19Content-Hash: blake3:c60ca71925e3dec29b8b9dfc1e2775c899c932e93fca99e659fb0aac87ac79e420Source-Hash: blake3:b863a9279a8e31251a475dd8c895529ec38eec6b6506af4fe5c874832e9a48a621Schema-Version: v122-->2324# html-to-markdown2526html-to-markdown is a high-performance HTML→Markdown converter with a Rust core and 12 native language bindings. It converts HTML to CommonMark Markdown, Djot, or plain text in a single pass, optionally extracting metadata, tables, inline images, and a structured document tree.2728Use this skill when writing code that:2930- Converts HTML strings, files, or live URLs to Markdown, Djot, or plain text31- Extracts metadata (title, OG tags, JSON-LD/Microdata/RDFa, headers, links, images, language) from HTML32- Extracts structured table data (GFM markdown + cell grids) from HTML33- Extracts a structured document-structure tree34- Extracts inline images (data URIs, SVGs) from HTML35- Uses preprocessing to clean noisy HTML (ads, navigation, forms) before conversion3637## Capability map3839| Capability | CLI | SDKs |40| ---------- | --- | ---- |41| HTML→Markdown / Djot / plain text | `html-to-markdown FILE` | `convert(html, options)` |42| Read HTML from stdin / file / URL | `cat f \| …`, `FILE`, `--url URL` | `convert(htmlString, …)` |43| ~30 config options (headings, code blocks, lists, escaping, wrapping…) | flags | `ConversionOptions` |44| Metadata extraction | `--json` (default-extracted) | `result.metadata` |45| Table extraction | `--json` → `tables[]` | `result.tables` |46| Document structure tree | `--json --include-structure` | `include_document_structure=true` |47| Inline image extraction | `--json --extract-inline-images` | `extract_images=true` |48| HTML preprocessing | `--preprocess [--preset …]` | `PreprocessingOptions` |49| Extraction-only (no Markdown body) | `--json --no-content` | options + read fields |5051## Installation5253### CLI5455```bash56# (Homebrew 6.0+ requires explicit trust for third-party taps)57brew trust xberg-io/tap58brew install xberg-io/tap/html-to-markdown59# or run without a persistent install (the CLI proxy package self-installs the binary):60npx @xberg-io/html-to-markdown-cli --help61uvx --from html-to-markdown-cli html-to-markdown --help62# or download a prebuilt binary from the latest GitHub release:63# https://github.com/xberg-io/html-to-markdown/releases/latest64# or build from source:65cargo install html-to-markdown-cli66```6768### Language SDKs6970```bash71pip install html-to-markdown # Python72npm install @xberg-io/html-to-markdown # TypeScript / Node.js73cargo add html-to-markdown-rs # Rust (features: metadata default; full = all)74gem install html-to-markdown # Ruby75composer require xberg-io/html-to-markdown # PHP76go get github.com/xberg-io/html-to-markdown/packages/go/v3 # Go77dotnet add package XbergIo.HtmlToMarkdown # C#78npm install @xberg-io/html-to-markdown-wasm # WASM79```8081- Java (Maven): `io.xberg:html-to-markdown`82- Elixir: `{:html_to_markdown, "~> 3.8"}` in `mix.exs`83- R: `install.packages("htmltomarkdown", repos = "https://xberg-io.r-universe.dev")`84- C (FFI): pre-built `.so` / `.dll` / `.dylib` from GitHub releases8586## CLI vs SDK — which to use8788- **CLI** — one-shot conversions, shell pipelines, fetching a single URL, ad-hoc metadata/table extraction via `--json | jq`. Flags only for conversion (`FILE` is positional; omit or use `-` for stdin); the only subcommand is `mcp`.89- **SDK** — embedding conversion in application code, batch processing, custom element conversion (visitor pattern, Rust), and tight loops where process spawn overhead matters.90- **MCP server** — `html-to-markdown mcp` exposes `convert_html` and `extract_metadata` as agent tools, so an MCP client can convert an HTML string directly with no shell-out. This plugin auto-registers it; see the **using-the-mcp-server** skill.9192Both share the same `ConversionResult` shape, so output is interchangeable.9394## When to use html-to-markdown vs xberg vs crawlberg9596- **html-to-markdown** — you already have HTML (a string, a file, or a single URL) and want clean Markdown plus structured metadata/tables. No OCR, no document parsing, no crawling.97- **xberg** — you have *documents* (PDF, Office, images, email, archives) and need full text/table/metadata extraction with optional OCR. Use it when the input is not already HTML.98- **crawlberg** — you need to *crawl or scrape many pages*, follow links, and handle JS-rendered sites with a headless-Chrome fallback. It uses html-to-markdown internally for the HTML→Markdown step.99100Rule of thumb: single HTML in → Markdown out = html-to-markdown. Many URLs / a site = crawlberg. Non-HTML documents = xberg.101102## CLI quick start103104```bash105# Convert a file to stdout106html-to-markdown input.html107108# Convert and save109html-to-markdown input.html -o output.md110111# Read from stdin112cat page.html | html-to-markdown113114# Fetch and convert a URL115html-to-markdown --url https://example.com > out.md116117# Full ConversionResult as JSON (content, tables, metadata, images, warnings)118html-to-markdown --json input.html119120# JSON with document structure tree121html-to-markdown --json --include-structure input.html122123# Extraction-only (no Markdown body)124html-to-markdown --json --no-content input.html125126# Aggressive web-page cleanup127html-to-markdown input.html --preprocess --preset aggressive128```129130## SDK quick start131132### Rust133134```rust135use html_to_markdown_rs::convert;136137let result = convert("<h1>Hello World</h1><p>A paragraph.</p>", None)?;138println!("{}", result.content.unwrap_or_default());139```140141### Python142143```python144from html_to_markdown import convert145146result = convert("<h1>Hello World</h1><p>A paragraph.</p>")147print(result.content) # # Hello World\n\nA paragraph.148print(result.metadata) # title, links, headers, …149```150151### TypeScript / Node.js152153```typescript154import { convert } from "@xberg-io/html-to-markdown";155156// Node's convert() returns a ConversionResult object directly.157const result = convert("<h1>Hello World</h1><p>A paragraph.</p>");158console.log(result.content);159```160161## ConversionResult fields162163All languages return the same structure (dict, object, or struct).164165| Field | Description |166| ----- | ----------- |167| `content` | Converted text (Markdown/Djot/plain). `null` only in extraction-only mode. |168| `metadata` | Title, OG, headers, links, images, structured data. |169| `tables` | Tables with `grid` (structured cells) and `markdown` fields. |170| `images` | Extracted inline images (requires inline-image extraction). |171| `document` | Structured document tree when structure extraction is enabled. |172| `warnings` | Non-fatal processing warnings (`message`, `kind`). |173174## Configuration175176All languages expose the same ~30 options. See [references/configuration.md](references/configuration.md) for the complete table. Common ones:177178| Option | Values | Default |179| ------ | ------ | ------- |180| `heading_style` | `atx`, `underlined`, `atx-closed` | `atx` |181| `code_block_style` | `backticks`, `indented`, `tildes` | `backticks` |182| `output_format` | `markdown`, `djot`, `plain` | `markdown` |183| `wrap` / `wrap_width` | bool / 20–500 | off / `80` |184| `autolinks` (SDK) / `--no-autolinks` (CLI) | bool / flag | `true` (on); disable in CLI with `--no-autolinks` |185| preprocessing | `minimal` / `standard` / `aggressive` | off |186187### Rust (builder)188189```rust190use html_to_markdown_rs::{convert, ConversionOptions, HeadingStyle, OutputFormat};191192let options = ConversionOptions::builder()193 .heading_style(HeadingStyle::Atx)194 .output_format(OutputFormat::Markdown)195 .wrap(true)196 .wrap_width(100)197 .build();198let result = convert(html, Some(options))?;199```200201### Python (dataclass)202203```python204from html_to_markdown import convert, ConversionOptions, PreprocessingOptions205206result = convert(207 html,208 ConversionOptions(heading_style="atx", wrap=True, wrap_width=100),209 PreprocessingOptions(enabled=True, preset="aggressive"),210)211```212213## Metadata extraction214215Metadata is extracted by default; in the CLI it appears under `metadata` in `--json` output. Fields include `document` (title, description, language, charset, open_graph), `headers`, `links` (with `link_type`), `images`, and `structured_data` (JSON-LD/Microdata/RDFa). See the **extracting-metadata** skill for details.216217## Table extraction218219Tables appear in `result.tables`, each with a pre-rendered `markdown` string and a structured cell `grid`. Markdown tables also appear inline in `content`. See the **extracting-tables** skill.220221## Document structure extraction222223Enable structure extraction (`--include-structure` on the CLI, `include_document_structure=true` in SDKs) to get a semantic node tree under `document`. Node types include `heading`, `paragraph`, `list`, `list_item`, `table`, `image`, `code`, `quote`, `group`, `metadata_block`.224225## Common pitfalls2262271. **`convert()` returns a result object, not a string.** Access `.content` for the Markdown text. This holds for Node.js too — `convert()` returns a `ConversionResult` object directly; do **not** `JSON.parse()` it.2282. **`--json` outputs JSON, not Markdown.** Omit `--json` for plain Markdown.2293. **`--include-structure`, `--extract-inline-images`, and `--no-content` require `--json`.**2304. **The conversion CLI is flags-only.** `FILE` is positional; the only subcommand is `mcp` (starts the MCP server).2315. **`--preset`, `--keep-navigation`, `--keep-forms` require `--preprocess`.**232233## Additional resources234235- **[CLI Reference](references/cli-reference.md)** — every flag, JSON shape, exit codes236- **[Configuration Reference](references/configuration.md)** — all 30+ options with defaults237- **[Rust API Reference](references/rust-api.md)** — signatures, builder, feature flags238- **[Python API Reference](references/python-api.md)** — functions, dataclasses, type hints239- **[TypeScript API Reference](references/typescript-api.md)** — functions, interfaces, Buffer support240- **[Other Bindings](references/other-bindings.md)** — Go, Ruby, PHP, Java, C#, Elixir, R, WASM, C FFI241242GitHub: <https://github.com/xberg-io/html-to-markdown>