xberg-io/html-to-markdown / .ai-rulez/skills/core-conversion-architecture
core-conversion-architecture
VerifiedHow 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.
Core Conversion Architecture
All paths are under crates/html-to-markdown/src/.
Pipeline
convert()inconvert_api.rschecksmax_input_size, normalizes the input, tries Tier-1, then falls back to Tier-2.- Tier-1: byte scanner in
converter/tier1/. - Tier-2: DOM walk over the
dommodule, built on astral-html,walk_nodeinconverter/main.rs; html5ever is used for tree repair. ConversionOptions::tier_strategy(Autodefault,Tier2,Tier1testkit only) picks the path.- Per-element converters live under
converter/(block/,inline/,list/,form/,media/,semantic/,text/). - Output is shaped by
ConversionOptionsinoptions/conversion.rs(heading style, list indent, code block style, newline style, whitespace mode). - Caller traversal hooks:
HtmlVisitortrait invisitor/traits.rs(featurevisitor). There is noDomWalkertrait.
Input safety (not output sanitization)
- Converted Markdown is not safe to render as trusted content; callers sanitize downstream. See
SECURITY.md. validate_input()invalidation.rsrejects 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>) returnsConversionError::InputTooLarge; default isNonenatively and 2 MiB on wasm32.max_depthbounds the Tier-2 walk to avoid stack overflow;effective_max_depthinconverter/main_helpers.rsdefaults it and clamps caller values to a ceiling.ConversionError::SanitizationErrorexists inerror.rsand 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |