HTML to Markdown Converter

Warnings

• breaking Version 2.x introduced a complete rewrite with a Rust core, leading to significant performance gains but also breaking changes in the API. While a `v1_compat` module was provided, users upgrading from 1.x should review the changelog for necessary code adjustments.
  Fix: Consult the library's CHANGELOG for specific migration steps. Consider using `html_to_markdown.v1_compat` if direct migration is complex.
• gotcha Markdown is a less expressive format than HTML. Complex HTML structures, inline styles, and certain advanced tags (e.g., `<script>`, `<style>`) will be simplified or entirely removed during conversion, potentially leading to a loss of original formatting or functionality.
  Fix: Pre-process HTML with a tool like BeautifulSoup to simplify or strip unwanted elements before conversion. Review converted Markdown carefully for fidelity.
• gotcha Conversion of complex HTML tables (e.g., with `colspan`, `rowspan`, nested elements) and `<code>`/`<pre>` blocks might not perfectly retain original formatting or indentation in Markdown. This can lead to less readable or incorrectly structured output.
  Fix: For critical code blocks or tables, manually verify the output. Consider using the 'Visitor Pattern' feature (`convert_with_visitor`) for fine-grained control over specific element conversions, especially for `pre` and `code` tags.
• gotcha The primary `convert()` function only returns the Markdown string. If you need to extract structured metadata like titles, links, or headings from the HTML during conversion, you must use `convert_with_metadata()` which returns a dictionary including both content and metadata.
  Fix: Use `from html_to_markdown import convert_with_metadata` and process the returned dictionary, e.g., `result = convert_with_metadata(html_content); markdown_content = result['content']; metadata = result['metadata']`.

Install

• pip install html-to-markdown Install with pip

Imports

• convert

  from html_to_markdown import convert

  Primary function for basic HTML to Markdown conversion.
• ConversionOptions

  from html_to_markdown import ConversionOptions

  Used to customize conversion behavior (e.g., heading style, output format).
• convert_with_metadata

  from html_to_markdown import convert_with_metadata

  Use to extract Markdown content along with structured metadata (headers, links, images).

Quickstart

This quickstart demonstrates basic HTML to Markdown conversion using the `convert` function. It also shows how to apply `ConversionOptions` to customize the output format, such as specifying heading styles or using Djot instead of standard Markdown.

from html_to_markdown import convert, ConversionOptions

html_content = """
<h1>Welcome</h1>
<p>This is <strong>bold</strong> and <em>italic</em> text.</p>
<ul>
    <li>Item 1</li>
    <li>Item 2</li>
</ul>
"""

# Basic conversion
markdown_output = convert(html_content)
print(f"Default Markdown:\n{markdown_output}")

# Conversion with options
options = ConversionOptions(
    heading_style="atx",
    list_indent_width=2,
    output_format="commonmark"
)
formatted_markdown = convert(html_content, options)
print(f"\nFormatted Markdown (CommonMark):\n{formatted_markdown}")

# Example for Djot output (another lightweight markup language)
djot_options = ConversionOptions(output_format="djot")
djot_output = convert(html_content, djot_options)
print(f"\nDjot Output:\n{djot_output}")