Visitor Pattern v2.23.0¶

The visitor pattern allows you to customize how specific HTML elements are converted to Markdown. Instead of modifying the library itself, you provide callback functions that intercept elements during conversion and return custom output.

What Is the Visitor Pattern?¶

In html-to-markdown, a visitor is an object (or set of callbacks) that receives notifications as the conversion engine encounters HTML elements. For each element type, you can implement a handler that decides what to do:

• Continue -- use the default conversion logic
• Custom -- replace the default output with your own Markdown
• Skip -- omit the element entirely from output
• Preserve HTML -- keep the raw HTML in the Markdown output

This gives you fine-grained control over conversion behavior without forking the library or writing a full converter from scratch.

How It Works in html-to-markdown¶

During DOM traversal, the conversion engine checks whether a visitor is registered. When an element matches a visitor callback, the engine:

1. Builds a NodeContext with element metadata (tag name, attributes, depth, parent info)
2. Calls the appropriate visitor method (e.g., visit_link, visit_heading, visit_image)
3. Inspects the return value to determine output behavior
4. Falls back to default conversion if no callback is registered for that element type

sequenceDiagram
    participant Engine as Conversion Engine
    participant Visitor as User Visitor

    Engine->>Engine: Encounter <a href="...">
    Engine->>Visitor: visit_link(context, href, text, title)
    Visitor-->>Engine: Custom("[text](modified-url)")
    Engine->>Engine: Use custom output

    Engine->>Engine: Encounter <h1>
    Engine->>Visitor: visit_heading(context, level, text, id)
    Visitor-->>Engine: Continue
    Engine->>Engine: Use default "# text" output

Visit Result Types¶

Every visitor callback returns one of these result types:

NodeContext¶

All visitor callbacks receive a context object with metadata about the current element:

Support Matrix¶

Not all language bindings support the visitor pattern. The table below shows current support:

Available Callbacks¶

Visitor implementations can override any combination of these callbacks. Unimplemented callbacks default to Continue (standard conversion).

Text and Formatting¶

Links and Media¶

Code¶

Structure¶

Lists¶

Tables¶

Generic Hooks¶

Common Use Cases¶

Content Filtering¶

Remove unwanted elements from conversion output:

visit_image -> Skip          # Remove all images
visit_link  -> Custom(text)  # Strip links, keep text

URL Rewriting¶

Transform URLs during conversion (e.g., converting relative paths to absolute, adding tracking parameters, or switching CDN domains):

visit_link(ctx, href, text, title):
    new_url = rewrite(href)
    return Custom("[{text}]({new_url})")

Domain-Specific Dialects¶

Generate non-standard Markdown for specific platforms:

• Slack/Discord: Custom emoji syntax, mention formatting
• Confluence: Wiki-style links and macros
• Obsidian: Internal link syntax [[page]]
• MDX: JSX component embedding

Content Enrichment¶

Add metadata or annotations during conversion:

visit_heading(ctx, level, text, id):
    anchor = generate_anchor(text)
    return Custom("#{level} {text} {{#{anchor}}}")

Security Filtering¶

Sanitize or rewrite potentially dangerous content:

visit_link(ctx, href, text, title):
    if is_javascript_url(href):
        return Skip
    return Continue

Further Reading¶

• Visitor Pattern Guide -- step-by-step implementation guide with code examples
• Conversion Pipeline -- how visitors fit into the overall pipeline
• Configuration Options -- non-visitor configuration options