kreuzberg-dev/.ai-rulez/skills/conversion-mapping-rules

Conversion Mapping Rules: HTML Elements to Markdown

Overview

This skill documents how html-to-markdown maps 60+ HTML element types to their Markdown equivalents. The conversion logic respects Markdown syntax variations (ATX vs Setext headings, fenced vs indented code, etc.) and maintains semantic accuracy.

Heading Elements (h1-h6)

ATX Style (Default)

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Implementation:

• Option: HeadingStyle::Atx (default)
• Each heading level uses n hashes
• Single space after hashes required
• Trailing hashes optional (ATX closed style adds them)

HTML Example:

<h1>Title</h1>          → # Title
<h2 id="intro">Intro</h2> → ## Intro
<h3>Detail</h3>         → ### Detail

Setext/Underlined Style

Heading 1
=========

Heading 2
---------

Implementation:

• Option: HeadingStyle::Underlined
• H1: = characters for full line width
• H2: - characters for full line width
• H3+ not supported in Setext (fallback to ATX)

HTML Example:

<h1>Main Title</h1>  → Main Title\n===========
<h2>Subtitle</h2>    → Subtitle\n---------
<h3>Detail</h3>      → ### Detail (fallback to ATX)

ATX Closed Style

# Heading 1 #

## Heading 2 ##

### Heading 3 ###

Implementation:

• Option: HeadingStyle::AtxClosed
• Closing hashes must match opening count
• Single space before closing hashes
• Less common, but valid Markdown

Block-Level Elements

Paragraph (<p>)

Mapping:

• Text content extracted and escaped
• Trailing/leading whitespace trimmed
• Single newline after paragraph

Example:

<p>This is a paragraph with <strong>bold</strong> text.</p>
→ This is a paragraph with **bold** text.\n

Division (<div>)

Behavior:

• Transparent wrapper for Markdown
• Content treated as block-level
• No wrapping markers in output
• Preserves child semantics

Example:

<div>
  <p>Paragraph inside div</p>
</div>
→ Paragraph inside div\n

Blockquote (<blockquote>)

Mapping:

• Each line prefixed with >
• Nested blockquotes: > >
• Handles multiple paragraphs

Example:

<blockquote>
  <p>Quote line 1</p>
  <p>Quote line 2</p>
</blockquote>
→ > Quote line 1\n>\n> Quote line 2\n

Preformatted Text (<pre>)

Behavior:

• Whitespace preserved exactly
• Treated as code block (see Code Blocks below)
• No entity decoding in content
• Trimmed and indented

Example:

<pre>    code with spaces</pre>
→ (indented code or fenced, depends on CodeBlockStyle)

Code Blocks

Indented Style (Default):

    line 1
    line 2
    line 3

Implementation:

• Option: CodeBlockStyle::Indented
• Each line prefixed with 4 spaces
• Requires blank line before/after
• CommonMark default

Fenced Backtick Style:

```language
code here

**Implementation:**
- Option: `CodeBlockStyle::Backticks`
- Triple backticks with optional language specifier
- Language from HTML class (e.g., `language-rust` → `rust`)
- Can contain blank lines

**Fenced Tilde Style:**
```markdown
~~~rust
code here
~~~

Implementation:

• Option: CodeBlockStyle::Tildes
• Triple tildes with optional language specifier
• Less common variant of fenced style

HTML Mapping:

<pre><code>simple code</code></pre>
<pre><code class="language-python">def foo(): pass</code></pre>
<pre>indented code</pre>

Horizontal Rule (<hr>)

Output: ---\n (three dashes)

Alternatives: ***, ___ all valid but standardized to ---

List Elements

Unordered Lists (<ul>)

Default Syntax (dashes):

- Item 1
- Item 2
  - Nested item
    - Deeply nested

Implementation:

• - marker (could be * or +, but - is default)
• Indentation for nesting: spaces or tabs
• Option: ListIndentType::Spaces (default) or ListIndentType::Tabs

Ordered Lists (<ol>)

1. First item
2. Second item
3. Third item

Implementation:

• 1. through 9. for first 9 items (reset per list)
• Number must be followed by . (dot space)
• Indentation matches unordered for nesting

List Items (<li>)

Behavior:

• Content can include block elements (paragraphs, code blocks)
• Continuation lines indented to match marker
• Multi-line items:

- First paragraph

  Second paragraph (indented)

HTML Example:

<ul>
  <li>
    <p>Item with paragraph</p>
    <p>Second paragraph</p>
  </li>
</ul>

Definition Lists (<dl>, <dt>, <dd>)

Term
:   Definition

Another Term
:   Definition 1
:   Definition 2

Implementation:

• <dt>: Term on its own line
• <dd>: Definition with : prefix and indentation
• Multiple definitions per term supported

Tables (<table>, <tr>, <td>, <th>)

Mapping:

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Implementation:

• <table> → GFM (GitHub Flavored Markdown) table
• <thead> content becomes header row
• <tbody> rows become data rows
• Cells separated by | pipes
• Separator row: |---|---| (minimum 3 dashes)
• Right-alignment: :---| Left: |:-- Center: :--:

Cell Content:

• Escaped for pipe characters (| → \|)
• Nested elements converted (e.g., <strong> → **)
• Newlines converted to <br> representation

Semantic HTML5 Elements

Article (<article>)

• Treated as transparent block wrapper
• No semantic markers in Markdown
• Content flows as-is

Section (<section>)

• Transparent block wrapper
• Could insert heading separator in future

Nav (<nav>)

• List-like wrapper
• Children converted normally
• Could insert navigation markers

Aside (<aside>)

• Optional blockquote prefix (configurable)
• Or treated as transparent block

Header (<header>)

• Transparent wrapper
• Content converted normally

Footer (<footer>)

• Transparent wrapper
• Could insert footer marker (e.g., ---\n)

Main (<main>)

• Transparent wrapper
• Content flows normally

Inline Elements

Emphasis (<em>, <i>)

Mapping: *text* or _text_

Implementation:

• Default: * (asterisk italic)
• No underscore escaping needed in this context
• Trimmed of excess whitespace

Example:

<em>emphasized</em>  → *emphasized*
<i>italic</i>        → *italic*

Strong (<strong>, <b>)

Mapping: **text**

Implementation:

• Double asterisks (bold)
• Trimmed of excess whitespace
• Can be nested with emphasis

Example:

<strong>bold</strong>           → **bold**
<b>bold</b>                     → **bold**
<strong><em>bold italic</em></strong> → ***bold italic***

Code (<code>)

Mapping: `text` (backtick inline code)

Implementation:

• Single backticks for inline
• Escaped if backticks present in content
• No entity decoding within code

Example:

<code>variable_name</code>        → `variable_name`
<code>don't</code>                → `don't`
<code>`already_quoted`</code>     → `` `already_quoted` ``

Link (<a href>)

Mapping: [link text](url "title")

Implementation:

• href attribute becomes URL
• Text content becomes link text
• title attribute becomes optional title (in quotes)
• URL preserved as-is (no extra encoding)
• Special link types:
  • href="#section" → Anchor link
  • href="/page" → Internal link (relative)
  • href="https://external.com" → External link
  • href="mailto:[email protected]" → Email link
  • href="tel:+1234567890" → Phone link

Examples:

<a href="https://example.com">Link</a>
→ [Link](https://example.com)

<a href="/page" title="My Page">Internal</a>
→ [Internal](/page "My Page")

<a href="#section">Anchor</a>
→ [Anchor](#section)

<a href="mailto:[email protected]">Email</a>
→ [Email](mailto:[email protected])

Image (<img>)

Mapping: ![alt text](url "title")

Implementation:

• src attribute becomes URL
• alt attribute becomes alt text
• title attribute becomes optional title
• Dimensions (width, height) captured in metadata
• Data URIs: ![alt](data:image/png;base64,...)
• Relative paths preserved

Examples:

<img src="photo.jpg" alt="A photo">
→ ![A photo](photo.jpg)

<img src="image.png" alt="Image" title="My Image" width="200" height="150">
→ ![Image](image.png "My Image")

<img src="data:image/png;base64,..." alt="Embedded">
→ ![Embedded](data:image/png;base64,...)

Line Break (<br>)

Mapping:

• Two spaces + newline: \n
• Or backslash + newline: \\\n

Option: NewlineStyle::Spaces (default) or NewlineStyle::Backslash

Example:

<p>Line 1<br>Line 2</p>
→ Line 1  \nLine 2\n

Strikethrough (<s>, <del>, <strike>)

Mapping: ~~strikethrough~~

Implementation:

• GFM strikethrough syntax (double tilde)
• Not standard Markdown, but widely supported
• Trimmed of excess whitespace

Example:

<del>removed text</del>  → ~~removed text~~
<s>strikethrough</s>     → ~~strikethrough~~

Subscript/Superscript (<sub>, <sup>)

Behavior:

• No native Markdown support
• Typically converted to plain text or HTML passthrough
• Implementation: Extract text content, no markup

Example:

H<sub>2</sub>O          → H2O (plain text)
E=mc<sup>2</sup>        → E=mc2 (plain text)

Mark/Highlight (<mark>)

Options:

1. HighlightStyle::DoubleEqual: ==text==
2. HighlightStyle::Html: <mark>text</mark>
3. HighlightStyle::Bold: **text**
4. HighlightStyle::None: plain text

Example:

<mark>highlighted</mark>
→ ==highlighted==  (DoubleEqual mode)
→ <mark>highlighted</mark>  (Html mode)
→ **highlighted**  (Bold mode)

Ruby Annotations (<ruby>, <rt>, <rp>)

Mapping:

• Japanese ruby text support
• Format: text {rt_text} or similar
• Implementation: Extract base text with rt annotation

Example:

<ruby>漢字<rt>かんじ</rt></ruby>
→ 漢字 (かんじ)

Media Elements

Audio (<audio>)

Behavior:

• No direct Markdown equivalent
• Typically extracted as metadata or skipped
• Could insert link to source if src attribute

Handling:

<audio src="sound.mp3">Audio</audio>
→ (Skipped or converted to link in metadata)

Video (<video>)

Behavior:

• Similar to audio
• Could extract poster image
• Typically skipped in markdown output

Picture/Source (<picture>, <source>)

Behavior:

• Responsive image container
• Extract from child <img> inside
• Or use first source src

Form Elements

Input (<input>)

Behavior:

• Generally skipped or marked as form element
• Could convert to metadata about form structure
• Types: text, checkbox, radio, button, hidden

Implementation:

• Placeholder preserved in metadata
• Value not typically included in markdown

Select/Option (<select>, <option>)

Behavior:

• Converted to list or metadata
• Option text extracted
• Selected state noted

Button (<button>)

Behavior:

• Text content extracted (ignores <button> wrapper)
• Click handlers ignored
• Treated as inline text

Textarea (<textarea>)

Behavior:

• Content treated as code block or preformatted
• Whitespace preserved

Special Elements

SVG (<svg>)

Behavior:

• Can be preserved as inline image or skipped
• Feature: inline-images can extract inline SVG
• Typically rendered as-is in compatible markdown renderers

MathML (<math>)

Behavior:

• Skipped in standard markdown
• Could be preserved with feature gate
• Converted to LaTeX or plain text fallback

iframe (<iframe>)

Behavior:

• Generally skipped
• Could extract as metadata (video embeds, etc.)
• URL captured if needed

Whitespace and Formatting Context

Whitespace Mode

Normalized (default):

• Multiple spaces collapsed to single space
• Multiple newlines → single newline
• Leading/trailing whitespace trimmed per element

Strict:

• All whitespace preserved exactly
• Multiple spaces and newlines intact
• Useful for poetry, ASCII art, etc.

Text Escaping

Options:

• escape_asterisks: * → \*
• escape_underscores: _ → \_
• escape_misc: Special chars \ & < [ > ~ # = + | -`
• escape_ascii: All ASCII punctuation (CommonMark spec)

Example:

<p>Price: $10 & free shipping *limited time*</p>

escape_misc=true:
→ Price: $10 \& free shipping *limited time*

escape_asterisks=true:
→ Price: $10 & free shipping \*limited time\*

escape_ascii=true:
→ Price: \$10 \& free shipping \*limited time\*

Implementation Details Location

Key Files:

• /crates/html-to-markdown/src/converter.rs - Element dispatch and conversion
• /crates/html-to-markdown/src/options.rs - Style configuration enums
• /crates/html-to-markdown/src/text.rs - Text escaping and normalization

Element Dispatch Example

// From converter.rs pattern
match element.tag_name() {
    "h1" | "h2" | "h3" | "h4" | "h5" | "h6" => convert_heading(...),
    "p" => convert_paragraph(...),
    "a" => convert_link(...),
    "img" => convert_image(...),
    "strong" | "b" => convert_strong(...),
    "em" | "i" => convert_em(...),
    "code" => convert_code(...),
    "pre" => convert_pre(...),
    "blockquote" => convert_blockquote(...),
    "ul" | "ol" => convert_list(...),
    "li" => convert_list_item(...),
    "table" => convert_table(...),
    "br" => convert_br(...),
    "hr" => convert_hr(...),
    // ... 40+ more elements
    _ => convert_generic_element(...)
}

Complete Element Reference

See /crates/html-to-markdown/src/visitor.rs for exhaustive NodeType enum covering all 60+ supported elements.

Quick Reference Table

| HTML Element | Markdown Output | Notes | |--------------|-----------------|-------| | <h1> | # text | ATX style default | | <p> | text\n | Paragraph | | <strong> | **text** | Bold | | <em> | *text* | Italic | | <a href> | [text](url) | Link | | <img> | ![alt](src) | Image | | <ul> | - item | Unordered list | | <ol> | 1. item | Ordered list | | <code> | `text` | Inline code | | <pre> | Indented or fenced | Code block | | <blockquote> | > text | Quote | | <table> | GFM table | Pipe-delimited | | <br> | \n | Line break | | <hr> | --- | Horizontal rule | | <del> | ~~text~~ | Strikethrough | | <mark> | ==text== | Highlight (configurable) |