all2md.options.html

Configuration options for HTML parsing and rendering.

This module defines options for HTML document conversion with sanitization and security controls.

class all2md.options.html.HtmlRendererOptions

Bases: BaseRendererOptions

Configuration options for rendering AST to HTML format.

This dataclass contains settings specific to HTML generation, including document structure, styling, templating, and feature toggles.

Parameters:

standalone (bool, default True) – Generate complete HTML document with <html>, <head>, <body> tags. If False, generates only the content fragment. Ignored when template_mode is not None.
css_style ({"inline", "embedded", "external", "none"}, default "embedded") – How to include CSS styles: - “inline”: Add style attributes to elements - “embedded”: Include <style> block in <head> - “external”: Reference external CSS file - “none”: No styling
css_file (str or None, default None) – Path to external CSS file (used when css_style=”external”).
include_toc (bool, default False) – Generate table of contents from headings.
syntax_highlighting (bool, default True) – Add language classes to code blocks for syntax highlighting.
render_mermaid (bool, default False) – Render fenced code blocks whose language is mermaid as <pre class="mermaid"> (a hook for a client-side mermaid.js) instead of the usual <pre><code>. Used by the view/serve commands.
escape_html (bool, default True) – Escape HTML special characters in text content.
math_renderer ({"mathjax", "katex", "none"}, default "mathjax") – Math rendering library to use for MathML/LaTeX math: - “mathjax”: Include MathJax CDN script - “katex”: Include KaTeX CDN script - “none”: Render math as plain text
html_passthrough_mode ({"pass-through", "escape", "drop", "sanitize"}, default "pass-through") – How to handle HTMLBlock and HTMLInline nodes: - “pass-through”: Pass through unchanged (use only with trusted content) - “escape”: HTML-escape the content - “drop”: Remove HTML content entirely - “sanitize”: Remove dangerous elements/attributes (requires bleach for best results)
language (str, default "en") – Document language code (ISO 639-1) for the <html lang=”…”> attribute. Can be overridden by document metadata.
external_links_new_tab (bool, default False) – If True, external links (absolute http/https/ftp/mailto URLs) are rendered with target=”_blank” rel=”noopener noreferrer” so they open in a new tab. Relative and anchor links are unaffected. Used by the view/serve commands.
template_mode ({"inject", "replace", "jinja"} or None, default None) – Template mode for rendering HTML: - None: Use standalone mode (default behavior) - “inject”: Inject content into existing HTML file at selector - “replace”: Replace placeholders in template file - “jinja”: Use Jinja2 template engine with full context When set, standalone is ignored.
template_file (str or None, default None) – Path to template file (required when template_mode is not None).
template_selector (str, default "#content") – CSS selector for injection target (used with template_mode=”inject”).
toc_selector (str or None, default None) – CSS selector for separate TOC injection point (used with template_mode=”inject”). If not set, TOC is included with content at template_selector. Allows placing TOC in a different location like a sidebar or header.
injection_mode ({"append", "prepend", "replace"}, default "replace") – How to inject content at selector (used with template_mode=”inject”): - “append”: Add content after existing content - “prepend”: Add content before existing content - “replace”: Replace existing content
content_placeholder (str, default "{CONTENT}") – Placeholder string to replace with content (used with template_mode=”replace”).
css_class_map (dict[str, str | list[str]] or None, default None) – Map AST node type names to custom CSS classes. Example: {“Heading”: “article-heading”, “CodeBlock”: [“code”, “highlight”]}
allow_remote_scripts (bool, default False) – Allow loading remote scripts (e.g., MathJax/KaTeX from CDN). Default is False for security - requires explicit opt-in for CDN usage. When False and math_renderer != ‘none’, will raise a warning.
csp_enabled (bool, default False) – Add Content-Security-Policy meta tag to standalone HTML documents. Helps prevent XSS attacks by restricting resource loading.
csp_policy (str or None, default (secure policy)) – Custom Content-Security-Policy header value. If None, uses default: “default-src ‘self’; script-src ‘self’; style-src ‘self’ ‘unsafe-inline’;”
comment_mode ({"native", "visible", "ignore"}, default "native") – How to render Comment and CommentInline AST nodes: - “native”: Render as HTML comments (<!– Comment by Author: text –>) - “visible”: Render as visible <div>/<span> elements with class=”comment” and metadata in data attributes - “ignore”: Skip comment nodes entirely This controls presentation of comments from DOCX reviewer comments, source HTML comments, and other format-specific annotations.

Examples

Inject into existing HTML:

>>> options = HtmlRendererOptions(
...     template_mode="inject",
...     template_file="layout.html",
...     template_selector="#main-content"
... )

Replace placeholders:

>>> options = HtmlRendererOptions(
...     template_mode="replace",
...     template_file="template.html",
...     content_placeholder="{CONTENT}"
... )

Use Jinja2 template:

>>> options = HtmlRendererOptions(
...     template_mode="jinja",
...     template_file="article.html"
... )

Custom CSS classes:

>>> options = HtmlRendererOptions(
...     css_class_map={"Heading": "prose-heading", "CodeBlock": "code-block"}
... )

standalone: bool = True

css_style: Literal['inline', 'embedded', 'external', 'none'] = 'embedded'

css_file: str | None = None

include_toc: bool = False

syntax_highlighting: bool = True

render_mermaid: bool = False

escape_html: bool = True

math_renderer: Literal['mathjax', 'katex', 'none'] = 'mathjax'

html_passthrough_mode: Literal['pass-through', 'escape', 'drop', 'sanitize'] = 'escape'

language: str = 'en'

external_links_new_tab: bool = False

template_mode: Literal['inject', 'replace', 'jinja'] | None = None

template_file: str | None = None

template_selector: str = '#content'

toc_selector: str | None = None

injection_mode: Literal['append', 'prepend', 'replace'] = 'replace'

content_placeholder: str = '{CONTENT}'

css_class_map: dict[str, str | list[str]] | None = None

allow_remote_scripts: bool = False

csp_enabled: bool = True

csp_policy: str | None = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';"

comment_mode: Literal['native', 'visible', 'ignore'] = 'native'

__init__(fail_on_resource_errors: bool = False, max_asset_size_bytes: int = 52428800, metadata_policy: MetadataRenderPolicy = <factory>, creator: str | None = 'all2md', standalone: bool = True, css_style: CssStyle = 'embedded', css_file: str | None = None, include_toc: bool = False, syntax_highlighting: bool = True, render_mermaid: bool = False, escape_html: bool = True, math_renderer: MathRenderer = 'mathjax', html_passthrough_mode: HtmlPassthroughMode = 'escape', language: str = 'en', external_links_new_tab: bool = False, template_mode: TemplateMode | None = None, template_file: str | None = None, template_selector: str = '#content', toc_selector: str | None = None, injection_mode: InjectionMode = 'replace', content_placeholder: str = '{CONTENT}', css_class_map: dict[str, str | list[str]] | None=None, allow_remote_scripts: bool = False, csp_enabled: bool = True, csp_policy: str | None = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';", comment_mode: HtmlCommentMode = 'native') → None

class all2md.options.html.HtmlOptions

Bases: BaseParserOptions, AttachmentOptionsMixin

Configuration options for HTML-to-Markdown conversion.

This dataclass contains settings specific to HTML document processing, including heading styles, title extraction, image handling, content sanitization, and advanced formatting options. Inherits attachment handling from AttachmentOptionsMixin for images and embedded media.

Parameters:

extract_title (bool, default False) – Whether to extract and use the HTML <title> element.
convert_nbsp (bool, default False) – Whether to convert non-breaking spaces ( ) to regular spaces in the output.
strip_dangerous_elements (bool, default False) – Whether to remove potentially dangerous HTML elements (script, style, etc.) and event handler attributes (onclick, onload, etc.).
strip_framework_attributes (bool, default False) – Whether to remove JavaScript framework attributes (Alpine.js x-, Vue.js v-, Angular ng-, HTMX hx-, etc.) that can execute code in framework contexts. Only needed if output HTML will be rendered in browsers with these frameworks.
detect_table_alignment (bool, default True) – Whether to automatically detect table column alignment from CSS/attributes.
allowed_attributes (tuple[str, ...] | dict[str, tuple[str, ...]] | None, default None) – Whitelist of allowed HTML attributes. Supports two modes: - Global allowlist: tuple of attribute names applied to all elements - Per-element allowlist: dict mapping element names to tuples of allowed attributes Note: When using CLI, pass complex dict structures as JSON strings for proper parsing.
base_url (str or None, default None) – Base URL for resolving relative hrefs in <a> tags. This is separate from attachment_base_url (used for images/assets). Allows precise control over navigational link URLs vs. resource URLs.

Examples

Convert and extract page title:

>>> options = HtmlOptions(extract_title=True)

Convert with content sanitization:

>>> options = HtmlOptions(strip_dangerous_elements=True, convert_nbsp=True)

Use global attribute allowlist:

>>> options = HtmlOptions(allowed_attributes=('class', 'id', 'href', 'src'))

Use per-element attribute allowlist:

>>> options = HtmlOptions(allowed_attributes={
...     'img': ('src', 'alt', 'title'),
...     'a': ('href', 'title'),
...     'div': ('class', 'id')
... })

Extract only the readable article content:

>>> options = HtmlOptions(extract_readable=True)

extract_title: bool = False

convert_nbsp: bool = False

strip_dangerous_elements: bool = False

strip_framework_attributes: bool = False

detect_table_alignment: bool = True

network: NetworkFetchOptions

local_files: LocalFileAccessOptions

strip_comments: bool = True

collapse_whitespace: bool = True

extract_readable: bool = False

br_handling: Literal['newline', 'space'] = 'newline'

allowed_elements: tuple[str, ...] | None = None

allowed_attributes: tuple[str, ...] | dict[str, tuple[str, ...]] | None = None

figures_parsing: Literal['blockquote', 'paragraph', 'image_with_caption', 'caption_only', 'html', 'skip'] = 'blockquote'

details_parsing: Literal['blockquote', 'paragraph', 'html', 'skip'] = 'blockquote'

extract_microdata: bool = True

base_url: str | None = None

html_parser: Literal['html.parser', 'html5lib', 'lxml'] = 'html.parser'

__init__(attachment_mode: AttachmentMode = 'alt_text', alt_text_mode: AltTextMode = 'default', attachment_output_dir: str | None = None, attachment_base_url: str | None = None, max_asset_size_bytes: int = 52428800, attachment_filename_template: str = '{stem}_{type}{seq}.{ext}', attachment_overwrite: AttachmentOverwriteMode = 'unique', attachment_deduplicate_by_hash: bool = False, attachments_footnotes_section: str | None = 'Attachments', extract_metadata: bool = False, extract_title: bool = False, convert_nbsp: bool = False, strip_dangerous_elements: bool = False, strip_framework_attributes: bool = False, detect_table_alignment: bool = True, network: NetworkFetchOptions = <factory>, local_files: LocalFileAccessOptions = <factory>, strip_comments: bool = True, collapse_whitespace: bool = True, extract_readable: bool = False, br_handling: BrHandling = 'newline', allowed_elements: tuple[str, ...] | None=None, allowed_attributes: tuple[str, ...] | dict[str, tuple[str, ...]] | None=None, figures_parsing: FiguresParsing = 'blockquote', details_parsing: DetailsParsing = 'blockquote', extract_microdata: bool = True, base_url: str | None = None, html_parser: HtmlParser = 'html.parser') → None