all2md.options.markdown

Configuration options for Markdown parsing and rendering.

This module defines options for Markdown conversion with flavor support.

class all2md.options.markdown.MarkdownParserOptions

Bases: BaseParserOptions

Configuration options for Markdown-to-AST parsing.

This dataclass contains settings specific to parsing Markdown documents into AST representation, supporting various Markdown flavors and extensions.

Parameters:

• flavor ({"gfm", "commonmark", "multimarkdown", "pandoc", "kramdown", "markdown_plus"}, default "gfm") – Markdown flavor to parse. Determines which extensions are enabled.

• parse_tables (bool, default True) – Whether to parse table syntax (GFM pipe tables).

• parse_footnotes (bool, default True) – Whether to parse footnote references and definitions.

• parse_math (bool, default True) – Whether to parse inline ($…$) and block ($$…$$) math.

• parse_task_lists (bool, default True) – Whether to parse task list checkboxes (- [ ] and - [x]).

• parse_definition_lists (bool, default True) – Whether to parse definition lists (term : definition).

• parse_strikethrough (bool, default True) – Whether to parse strikethrough syntax (~~text~~).

• parse_marks (bool, default True) – Whether to parse the inline mark family used by Material for MkDocs / pymdownx: highlight (==text==), insert/underline (^^text^^), superscript (^text^) and subscript (~text~).

• parse_admonitions (bool, default True) – Whether to parse Material for MkDocs admonitions (!!! note "Title") and collapsible admonitions (??? note / ???+ note).

flavor: Literal['gfm', 'commonmark', 'multimarkdown', 'pandoc', 'kramdown', 'markdown_plus'] = 'gfm'

parse_tables: bool = True

parse_footnotes: bool = True

parse_math: bool = True

parse_task_lists: bool = True

parse_definition_lists: bool = True

parse_strikethrough: bool = True

parse_marks: bool = True

parse_admonitions: bool = True

parse_frontmatter: bool = True

__init__(extract_metadata: bool = False, flavor: Literal['gfm', 'commonmark', 'multimarkdown', 'pandoc', 'kramdown', 'markdown_plus'] = 'gfm', parse_tables: bool = True, parse_footnotes: bool = True, parse_math: bool = True, parse_task_lists: bool = True, parse_definition_lists: bool = True, parse_strikethrough: bool = True, parse_marks: bool = True, parse_admonitions: bool = True, parse_frontmatter: bool = True) → None

class all2md.options.markdown.MarkdownRendererOptions

Bases: BaseRendererOptions

Markdown rendering options for converting AST to Markdown text.

When a flavor is specified, default values for unsupported_table_mode and unsupported_inline_mode are automatically set to flavor-appropriate values unless explicitly overridden. This is handled via the __new__ method to apply flavor-aware defaults before instance creation.

This dataclass contains settings that control how Markdown output is formatted and structured. These options are used by multiple conversion modules to ensure consistent Markdown generation.

Parameters:

• escape_special (bool, default True) – Whether to escape special Markdown characters in text content. When True, characters like *, _, #, [, ], (, ), \ are escaped to prevent unintended formatting.

• emphasis_symbol ({"*", "_"}, default "*") – Symbol to use for emphasis/italic formatting in Markdown.

• bullet_symbols (str, default "*-+") – Characters to cycle through for nested bullet lists.

• list_indent_width (int, default 4) – Number of spaces to use for each level of list indentation.

• underline_mode ({"html", "markdown", "ignore"}, default "markdown") – Fallback for flavors that don’t natively support underline. Flavors that do (markdown_plus) always emit ^^text^^; for the rest: - “markdown”: Use ^^text^^ (the pymdownx insert spelling; roundtrips, needs an extension to render) - “html”: Use <u>text</u> tags (wider display support, but escaped on roundtrip) - “ignore”: Strip underline formatting

• superscript_mode ({"html", "markdown", "ignore"}, default "markdown") – Fallback for flavors that don’t natively support superscript. Flavors that do (markdown_plus) always emit ^text^; for the rest: - “markdown”: Use ^text^ (roundtrips; non-standard, needs an extension to render) - “html”: Use ^text tags (wider display support, but escaped on roundtrip) - “ignore”: Strip superscript formatting

• subscript_mode ({"html", "markdown", "ignore"}, default "markdown") – Fallback for flavors that don’t natively support subscript. Flavors that do (markdown_plus) always emit ~text~; for the rest: - “markdown”: Use ~text~ (roundtrips; non-standard, needs an extension to render) - “html”: Use _text tags (wider display support, but escaped on roundtrip) - “ignore”: Strip subscript formatting

• use_hash_headings (bool, default True) – Whether to use # syntax for headings instead of underline style. When True, generates “# Heading” style. When False, generates “Headingn=======” style for level 1 and “Headingn——-” for levels 2+.

• flavor ({"gfm", "commonmark", "markdown_plus"}, default "gfm") – Markdown flavor/dialect to use for output: - “gfm”: GitHub Flavored Markdown (tables, strikethrough, task lists) - “commonmark”: Strict CommonMark specification - “markdown_plus”: All extensions enabled (footnotes, definition lists, etc.)

• unsupported_table_mode ({"drop", "ascii", "force", "html"}, default "force") – How to handle tables when the selected flavor doesn’t support them: - “drop”: Skip table entirely - “ascii”: Render as ASCII art table - “force”: Render as pipe table anyway (may not be valid for flavor) - “html”: Render as HTML <table>

• unsupported_inline_mode ({"plain", "force", "html"}, default "plain") – How to handle inline elements unsupported by the selected flavor: - “plain”: Render content without the unsupported formatting - “force”: Use markdown syntax anyway (may not be valid for flavor) - “html”: Use HTML tags (e.g., <u> for underline)

• heading_level_offset (int, default 0) – Shift all heading levels by this amount (positive or negative). Useful when collating multiple documents into a parent document with existing structure.

• code_fence_char ({"`", "~"}, default "`") – Character to use for code fences (backtick or tilde).

• code_fence_min (int, default 3) – Minimum length for code fences (typically 3).

• collapse_blank_lines (bool, default True) – Collapse multiple consecutive blank lines into at most 2 (normalizing whitespace).

• link_style ({"inline", "reference"}, default "inline") – Link style to use: - “inline”: [text](url) style links - “reference”: [text][ref] style with reference definitions at end

• reference_link_placement ({"end_of_document", "after_block"}, default "end_of_document") – Where to place reference link definitions when using reference-style links: - “end_of_document”: All reference definitions at document end (current behavior) - “after_block”: Reference definitions placed after each block-level element

• autolink_bare_urls (bool, default False) – Automatically convert bare URLs (e.g., http://example.com) found in Text nodes into Markdown autolinks (<http://example.com>). Ensures all URLs are clickable.

• table_pipe_escape (bool, default True) – Whether to escape pipe characters (|) in table cell content.

• math_mode ({"latex", "mathml", "html"}, default "latex") – Preferred math representation for flavors that support math. When the requested representation is unavailable on a node, the renderer falls back to any available representation while preserving flavor constraints.

• html_passthrough_mode ({"pass-through", "escape", "drop", "sanitize"}, default "escape") – How to handle raw HTML content in markdown (HTMLBlock and HTMLInline nodes): - “pass-through”: Pass HTML through unchanged (use only with trusted content) - “escape”: HTML-escape the content to show as text (secure default) - “drop”: Remove HTML content entirely - “sanitize”: Remove dangerous elements/attributes (requires bleach for best results) Note: This does not affect fenced code blocks with language=”html”, which are always rendered as code and are already safe.

• comment_mode ({"html", "blockquote", "ignore"}, default "blockquote") – How to render Comment and CommentInline AST nodes: - “html”: Render as HTML comments (<!– Comment text –>) - “blockquote”: Render as blockquotes with attribution ([Comment by Author: text]) - “ignore”: Skip comment nodes entirely This controls presentation of comments from DOCX reviewer comments, HTML comments, and other format-specific annotations.

escape_special: bool = True

emphasis_symbol: Literal['*', '_'] = '*'

bullet_symbols: str = '*-+'

list_indent_width: int = 4

underline_mode: Literal['html', 'markdown', 'ignore'] = 'markdown'

superscript_mode: Literal['html', 'markdown', 'ignore'] = 'markdown'

subscript_mode: Literal['html', 'markdown', 'ignore'] = 'markdown'

use_hash_headings: bool = True

flavor: Literal['gfm', 'commonmark', 'multimarkdown', 'pandoc', 'kramdown', 'markdown_plus'] = 'gfm'

strict_flavor_validation: bool = False

unsupported_table_mode: Literal['drop', 'ascii', 'force', 'html'] | object = <object object>

unsupported_inline_mode: Literal['plain', 'force', 'html'] | object = <object object>

pad_table_cells: bool = False

prefer_setext_headings: bool = False

max_line_width: int | None = None

table_alignment_default: str = 'left'

heading_level_offset: int = 0

code_fence_char: Literal['`', '~'] = '`'

code_fence_min: int = 3

collapse_blank_lines: bool = True

link_style: Literal['inline', 'reference'] = 'inline'

reference_link_placement: Literal['end_of_document', 'after_block'] = 'end_of_document'

autolink_bare_urls: bool = False

table_pipe_escape: bool = True

math_mode: Literal['latex', 'mathml', 'html'] = 'latex'

metadata_frontmatter: bool = False

metadata_format: Literal['yaml', 'toml', 'json'] = 'yaml'

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

comment_mode: Literal['html', 'blockquote', 'ignore'] = 'blockquote'

__init__(fail_on_resource_errors: bool = False, max_asset_size_bytes: int = 52428800, metadata_policy: MetadataRenderPolicy = <factory>, creator: str | None = 'all2md', escape_special: bool = True, emphasis_symbol: EmphasisSymbol = '*', bullet_symbols: str = '*-+', list_indent_width: int = 4, underline_mode: UnderlineMode = 'markdown', superscript_mode: SuperscriptMode = 'markdown', subscript_mode: SubscriptMode = 'markdown', use_hash_headings: bool = True, flavor: FlavorType = 'gfm', strict_flavor_validation: bool = False, unsupported_table_mode: UnsupportedTableMode | object = <object object>, unsupported_inline_mode: UnsupportedInlineMode | object = <object object>, pad_table_cells: bool = False, prefer_setext_headings: bool = False, max_line_width: int | None = None, table_alignment_default: str = 'left', heading_level_offset: int = 0, code_fence_char: CodeFenceChar = '`', code_fence_min: int = 3, collapse_blank_lines: bool = True, link_style: LinkStyleType = 'inline', reference_link_placement: ReferenceLinkPlacement = 'end_of_document', autolink_bare_urls: bool = False, table_pipe_escape: bool = True, math_mode: MathMode = 'latex', metadata_frontmatter: bool = False, metadata_format: MetadataFormatType = 'yaml', html_passthrough_mode: HtmlPassthroughMode = 'escape', comment_mode: CommentMode = 'blockquote') → None

all2md.options.markdown.get_flavor_defaults(flavor: Literal['gfm', 'commonmark', 'multimarkdown', 'pandoc', 'kramdown', 'markdown_plus']) → dict[str, Any]

Get default option values appropriate for a markdown flavor.

This function returns recommended default values for unsupported_table_mode and unsupported_inline_mode based on the specified markdown flavor’s capabilities.

Parameters:

flavor (FlavorType) – The markdown flavor to get defaults for.

Returns:

Dictionary with default option values for the flavor, including: - unsupported_table_mode: How to handle tables unsupported by flavor - unsupported_inline_mode: How to handle inline elements unsupported by flavor

Return type:

dict[str, Any]

Examples

Get defaults for CommonMark (strict spec):

>>> defaults = get_flavor_defaults("commonmark")
>>> defaults["unsupported_table_mode"]
'html'

Get defaults for GFM (supports most features):

>>> defaults = get_flavor_defaults("gfm")
>>> defaults["unsupported_table_mode"]
'html'

Notes

The global defaults are “html” for both modes to ensure backward compatibility and universal fallback. These flavor-specific defaults provide optimized settings for each flavor:

• CommonMark: Strict spec, use HTML for unsupported features

  • unsupported_table_mode: “html” (tables not in spec)

  • unsupported_inline_mode: “html” (strikethrough, etc. not in spec)

• GFM: Most features supported, but use HTML for unsupported

  • unsupported_table_mode: “html” (tables supported, but HTML is safer)

  • unsupported_inline_mode: “html” (footnotes not supported)

• MultiMarkdown: Tables and footnotes supported, use HTML for unsupported

  • unsupported_table_mode: “html” (tables supported, but HTML is safer)

  • unsupported_inline_mode: “html” (task lists not supported)

• Pandoc/Kramdown: Comprehensive support, force everything

  • unsupported_table_mode: “force” (all table types supported)

  • unsupported_inline_mode: “force” (most inline elements supported)

• MarkdownPlus: Everything enabled, always force

  • unsupported_table_mode: “force”

  • unsupported_inline_mode: “force”

all2md.options.markdown.validate_flavor_compatibility(flavor: Literal['gfm', 'commonmark', 'multimarkdown', 'pandoc', 'kramdown', 'markdown_plus'], options: MarkdownRendererOptions) → list[str]

Validate option compatibility with markdown flavor and return warnings.

This function checks if the provided options are compatible with the selected markdown flavor’s capabilities. It returns a list of warning messages for incompatible configurations but does not raise errors, allowing users to override flavor defaults when desired.

Parameters:

• flavor (FlavorType) – The markdown flavor to validate against.

• options (MarkdownRendererOptions) – The markdown options to validate.

Returns:

List of warning messages for incompatible configurations. Empty list if all options are compatible.

Return type:

list[str]

Examples

Validate CommonMark with table-related options:

>>> md_opts = MarkdownRendererOptions(flavor="commonmark", pad_table_cells=True)
>>> warnings = validate_flavor_compatibility("commonmark", md_opts)
>>> # Will warn if unsupported_table_mode is "drop" with pad_table_cells=True

No warnings for compatible configuration:

>>> md_opts = MarkdownRendererOptions(flavor="gfm", pad_table_cells=True)
>>> warnings = validate_flavor_compatibility("gfm", md_opts)
>>> len(warnings)
0

Notes

Common warning scenarios:

• Using pad_table_cells=True when flavor doesn’t support tables AND unsupported_table_mode=”drop”

• Setting table-specific options with CommonMark unless using unsupported_table_mode=”force” or “html”