Skip to content
Skills Library
Programming · Learning & explanation

core-conversion-architecture

/core-conversion-architecture

How the core crate turns HTML into Markdown: Tier-1 scanner, Tier-2 DOM walk, element converters, input validation and depth limits. Use when changing conversion output, parsing, or input-safety behavior in crates/html-to-markdown.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

84/ 100Class: good
Format9 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

How the core crate turns HTML into Markdown: Tier-1 scanner, Tier-2 DOM walk, element converters, input validation and depth limits. Use when changing conversion output, parsing, or input-safety behavior in crates/html-to-markdown.

Original author description

How the core crate turns HTML into Markdown: Tier-1 scanner, Tier-2 DOM walk, element converters, input validation and depth limits. Use when changing conversion output, parsing, or input-safety behavior in crates/html-to-markdown.

How it works

  1. Pipeline
  2. Input safety (not output sanitization)
Original SKILL.md headings · 25 lines, 234 words
SKILL.md preview
---
type: Playbook
title: Core Conversion Architecture
description: "How the core crate turns HTML into Markdown: Tier-1 scanner, Tier-2 DOM walk, element converters, input validation and depth limits. Use when changing conversion output, parsing, or input-safety behavior in crates/html-to-markdown."
paths:
  - "crates/html-to-markdown/src/**"
x-ai-rulez:
  kind: skill
  id: core-conversion-architecture
  metadata:
    name: core-conversion-architecture
---

# Core Conversion Architecture

All paths are under `crates/html-to-markdown/src/`.

## Pipeline

- `convert()` in `convert_api.rs` checks `max_input_size`, normalizes the input, tries Tier-1, then falls back to Tier-2.
- Tier-1: byte scanner in `converter/tier1/`.
- Tier-2: astral-tl DOM walk, `walk_node` in `converter/main.rs`; html5ever is used for tree repair.
- `ConversionOptions::tier_strategy` (`Auto` default, `Tier2`, `Tier1` testkit only) picks the path.
- Per-element converters live under `converter/` (`block/`, `inline/`, `list/`, `form/`, `media/`, `semantic/`, `text/`).
- Output is shaped by `ConversionOptions` in `options/conversion.rs` (heading style, list indent, code block style, newline style, whitespace mode).
- Caller traversal hooks: `HtmlVisitor` trait in `visitor/traits.rs` (feature `visitor`). There is no `DomWalker` trait.

## Input safety (not output sanitization)

- Converted Markdown is not safe to render as trusted content; callers sanitize downstream. See `SECURITY.md`.
- `validate_input()` in `validation.rs` rejects binary input: gzip/zstd/zip/PDF magic bytes, excess NUL bytes, high control-character ratio, undeclared UTF-16. It does not inspect HTML elements, attributes or URLs.
- `max_input_size` (`Option<u64>`) returns `ConversionError::InputTooLarge`; default is `None` natively and 2 MiB on wasm32.
- `max_depth` bounds the Tier-2 walk to avoid stack overflow; `effective_max_depth` in `converter/main_helpers.rs` defaults it and clamps caller values to a ceiling.
- `ConversionError::SanitizationError` exists in `error.rs` and in binding error mappings, but the core never constructs it.
- Script and style are stripped (markup fidelity, not security); `javascript:`/`data:` URLs and event-handler attributes pass through.
- There is no `SafetyConfig`, URL scheme allow-list or attribute allow-list.
Files in this package (2)
  • SKILL.md 2 KB
  • index.md 1 KB

Versions

The database has no other skills named core-conversion-architecture.

Database snapshot: 13.11.2026 · package version 0d781e57b01d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100html-to-markdown
    Convert HTML to Markdown, Djot, or plain text with structured extraction. Use when writing code that calls html-to-markdown APIs in Rust, Python, TypeScript, Go, Ruby, PHP, Java, C#, Elixir, R, C, or WASM. Covers installation, conversion, configuration, metadata extraction,…
  • 100data-flow
    The JSON-to-custom-element rendering pipeline used for data tables and list-rendered content. Defines toTagName key conversion, the lifecycle from fetch to DOM, and the strict scope (data tables only — other features have their own patterns). Use when rendering tabular or list…
  • 100test-rust-core
    Build and test NeMo Relay Rust core, adaptive, and dynamic plugin crates; use for crates/core, crates/adaptive, crates/plugin, crates/worker, crates/worker-proto, crates/types, or shared runtime changes
  • 84html-to-markdown
    Convert HTML to Markdown, Djot, or plain text with structured extraction. Use when writing code that calls html-to-markdown APIs in Rust, Python, TypeScript, Go, Ruby, PHP, Java, C#, Elixir, R, C, or WASM. Covers installation, conversion, configuration, metadata extraction,…
  • 100document-conversion
    Use when converting between document formats. Covers HTML to Markdown, document to Markdown, PDF generation from HTML, and preserving structure through a conversion rather than losing it. Trigger on "convert this html to markdown", "turn this docx into markdown", "make a pdf…
  • 100officeimo-conversion-operator
    Use when contributing code that changes or validates OfficeIMO conversion behavior, especially DOCX/XLSX/PPTX/HTML/Markdown/PDF byte and stream APIs, browser-safe paths, or fidelity diagnostics. Prefer OfficeIMO core APIs first and keep hosts, websites, cmdlets, MCP tools, and demos thin.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.