Configuration Options¶

html-to-markdown provides comprehensive configuration through the ConversionOptions struct. This guide explains every option with examples.

Heading Style¶

Controls how HTML headings (<h1> through <h6>) are formatted.

from html_to_markdown import ConversionOptions, convert

options = ConversionOptions(heading_style="atx")
markdown = convert("<h1>Title</h1>", options)
# Output: # Title

import { convert } from '@kreuzberg/html-to-markdown';

const markdown = convert('<h1>Title</h1>', { headingStyle: 'atx' });

use html_to_markdown_rs::{convert, ConversionOptions, HeadingStyle};

let options = ConversionOptions {
    heading_style: HeadingStyle::Atx,
    ..Default::default()
};
let markdown = convert("<h1>Title</h1>", Some(options))?;

markdown = HtmlToMarkdown.convert("<h1>Title</h1>", heading_style: :atx)

$options = new ConversionOptions(headingStyle: 'Atx');
$markdown = $converter->convert('<h1>Title</h1>', $options);

Code Block Style¶

Controls how <pre><code> blocks are formatted.

The code_language option sets a default language for fenced code blocks when the HTML does not specify one:

options = ConversionOptions(
    code_block_style="backticks",
    code_language="python",  # Default language when none specified
)

List Options¶

Bullet List Marker¶

The bullets option controls the character(s) used for unordered list items. Characters cycle through nesting levels:

List Indent Width¶

The list_indent_width option controls the number of spaces per indentation level (default: 2):

options = ConversionOptions(list_indent_width=4)

List Indent Type¶

Choose between spaces (default) and tabs:

options = ConversionOptions(list_indent_type="spaces")  # or "tabs"

Text Formatting¶

Bold/Italic Symbol¶

The strong_em_symbol option sets the character used for bold and italic text:

Newline Style¶

Controls how <br> tags are rendered:

Subscript and Superscript¶

Custom symbols for <sub> and <sup> elements:

options = ConversionOptions(
    sub_symbol="~",   # <sub>text</sub> -> ~text~
    sup_symbol="^",   # <sup>text</sup> -> ^text^
)

Highlight Style¶

Controls how <mark> elements are rendered:

Escaping Options¶

Control which characters are escaped to prevent accidental Markdown formatting:

options = ConversionOptions(
    escape_asterisks=True,
    escape_underscores=True,
)
markdown = convert("Price: $10*2 = $20", options)
# Output: Price: $10\*2 = $20

Tag Preservation¶

Keep specific HTML elements as raw HTML in the output:

options = ConversionOptions(
    preserve_tags=["table", "svg", "details"],
)

See Tag Preservation for details.

Image Handling¶

Skip Images v2.21.0¶

Omit all <img> elements from output:

options = ConversionOptions(skip_images=True)
markdown = convert('<p>Text <img src="photo.jpg" alt="Photo"> more text</p>', options)
# Output: Text more text

Keep Inline Images In¶

Specify which parent elements should retain images as Markdown rather than converting to alt text:

options = ConversionOptions(
    keep_inline_images_in=["a", "strong"],
)

Links¶

Autolinks¶

When link text equals the URL, use compact autolink syntax:

options = ConversionOptions(autolinks=True)
markdown = convert('<a href="https://example.com">https://example.com</a>', options)
# Output: <https://example.com>

Default Title¶

Use the href as a link title when no title attribute exists:

options = ConversionOptions(default_title=True)

Tables¶

BR in Tables v2.22.4¶

Preserve line breaks inside table cells using <br> tags:

options = ConversionOptions(br_in_tables=True)

Whitespace and Wrapping¶

Whitespace Mode¶

Strip Newlines¶

Remove all newlines from HTML before processing (useful for minified HTML):

options = ConversionOptions(strip_newlines=True)

Text Wrapping¶

Enable automatic text wrapping at a specified column width:

options = ConversionOptions(
    wrap=True,
    wrap_width=80,  # Default is 80
)

Preprocessing¶

HTML preprocessing cleans up web content before conversion. It removes navigation, ads, forms, and other boilerplate.

from html_to_markdown import ConversionOptions, PreprocessingOptions

options = ConversionOptions(
    preprocessing=PreprocessingOptions(
        enabled=True,
        preset="standard",  # "minimal", "standard", or "aggressive"
    )
)

Override specific behaviors:

preprocessing = PreprocessingOptions(
    enabled=True,
    preset="standard",
    keep_navigation=True,   # Override: keep nav elements
    keep_forms=True,        # Override: keep form elements
)

Strip Tags¶

Remove specific HTML tags while keeping their text content:

options = ConversionOptions(
    strip_tags=["script", "style", "nav"],
)

This differs from preserve_tags (which keeps the HTML) and from the default behavior (which converts the element to Markdown).

Output Format v2.23.0¶

Convert to Markdown (default), Djot, or plain text:

options = ConversionOptions(output_format="markdown")  # or "djot", "plain"

Plain text mode strips all markup and returns only visible text content — useful for search indexing, text extraction, or feeding content to LLMs.

Block Element Handling¶

Convert As Inline¶

Treat block-level elements as inline during conversion (no paragraph breaks):

options = ConversionOptions(convert_as_inline=True)

This is useful when converting HTML fragments that will be inserted into an existing Markdown paragraph.

Full Configuration Example¶

from html_to_markdown import ConversionOptions, convert

options = ConversionOptions(
    heading_style="atx",
    code_block_style="backticks",
    code_language="",
    bullets="-",
    list_indent_width=2,
    strong_em_symbol="*",
    newline_style="backslash",
    highlight_style="double_equal",
    autolinks=True,
    wrap=True,
    wrap_width=80,
    preserve_tags=["svg"],
    skip_images=False,
    escape_asterisks=False,
    escape_underscores=False,
)

markdown = convert(html, options)

import { convert, ConversionOptions } from '@kreuzberg/html-to-markdown';

const options: ConversionOptions = {
  headingStyle: 'atx',
  codeBlockStyle: 'backticks',
  bullets: '-',
  listIndentWidth: 2,
  strongEmSymbol: '*',
  autolinks: true,
  wrap: true,
  wrapWidth: 80,
  preserveTags: ['svg'],
  skipImages: false,
};

const markdown = convert(html, options);

use html_to_markdown_rs::{convert, ConversionOptions, HeadingStyle, CodeBlockStyle};

let options = ConversionOptions {
    heading_style: HeadingStyle::Atx,
    code_block_style: CodeBlockStyle::Backticks,
    bullets: "-".to_string(),
    list_indent_width: 2,
    autolinks: true,
    wrap: true,
    wrap_width: 80,
    preserve_tags: vec!["svg".to_string()],
    ..Default::default()
};

let markdown = convert(html, Some(options))?;

Further Reading¶

• Basic Conversion -- getting started with simple conversions
• Tag Preservation -- deep dive into preserve_tags
• Performance -- optimization tips for configuration choices