all2md.renderers.markdown

Markdown rendering from AST.

This module provides the MarkdownRenderer class which converts AST nodes to markdown text. The renderer supports multiple markdown flavors and configurable rendering options.

The rendering process uses the visitor pattern to traverse the AST and generate markdown output. The renderer maintains context (indentation, list nesting) during traversal.

class all2md.renderers.markdown.MarkdownRenderer

Bases: NodeVisitor, InlineContentMixin, BaseRenderer

Render AST nodes to markdown text.

This class implements the visitor pattern to traverse an AST and generate markdown output. It supports multiple markdown flavors and configurable rendering options.

Parameters:: options (MarkdownOptions or None, default = None) – Markdown formatting options (shared with parsers)

Examples

Basic usage:

>>> from all2md.ast import Document, Heading, Text
>>> from all2md.options import MarkdownRendererOptions
>>> from all2md.renderers.markdown import MarkdownRenderer
>>> doc = Document(children=[
...     Heading(level=1, content=[Text(content="Title")])
... ])
>>> options = MarkdownRendererOptions(flavor="gfm")
>>> renderer = MarkdownRenderer(options)
>>> markdown = renderer.render_to_string(doc)
>>> print(markdown)
# Title

Initialize the Markdown renderer with options.

__init__(options: MarkdownRendererOptions | None = None): Initialize the Markdown renderer with options.

render_to_string(document: Document) → str

Render a document AST to markdown string.

Parameters:: document (Document) – The document node to render
Returns:: Markdown text
Return type:: str

visit_document(node: Document) → None

Render a Document node.

Parameters:: node (Document) – Document to render

visit_heading(node: Heading) → None

Render a Heading node.

Parameters:: node (Heading) – Heading to render

visit_paragraph(node: Paragraph) → None

Render a Paragraph node.

Parameters:: node (Paragraph) – Paragraph to render

visit_code_block(node: CodeBlock) → None

Render a CodeBlock node.

Parameters:: node (CodeBlock) – Code block to render

visit_block_quote(node: BlockQuote) → None

Render a BlockQuote node.

Handles three cases:

A Material for MkDocs admonition (source_format == "mkdocs") rendered to a flavor that supports admonitions becomes a native !!! / ??? block.
Any other admonition (RST, or mkdocs on a non-supporting flavor) degrades to a quote with a bold label (e.g. > **Note:** ...).
A plain block quote is quoted as usual.

Parameters:: node (BlockQuote) – Block quote to render

visit_list(node: List) → None

Render a List node.

Parameters:: node (List) – List to render

visit_list_item(node: ListItem) → None

Render a ListItem node.

Parameters:: node (ListItem) – List item to render

visit_table(node: Table) → None

Render a Table node.

Parameters:: node (Table) – Table to render

visit_table_row(node: TableRow) → None

Render a TableRow node.

Parameters:: node (TableRow) – Table row to render

visit_table_cell(node: TableCell) → None

Render a TableCell node.

Parameters:: node (TableCell) – Table cell to render

visit_thematic_break(node: ThematicBreak) → None

Render a ThematicBreak node.

Parameters:: node (ThematicBreak) – Thematic break to render

visit_html_block(node: HTMLBlock) → None

Render an HTMLBlock node.

Parameters:: node (HTMLBlock) – HTML block to render

visit_comment(node: Comment) → None

Render a Comment node (block-level).

Parameters:: node (Comment) – Comment block to render

visit_text(node: Text) → None

Render a Text node.

Parameters:: node (Text) – Text to render

visit_emphasis(node: Emphasis) → None

Render an Emphasis node.

Parameters:: node (Emphasis) – Emphasis to render

visit_strong(node: Strong) → None

Render a Strong node.

Parameters:: node (Strong) – Strong to render

visit_code(node: Code) → None

Render a Code node.

Parameters:: node (Code) – Code to render

visit_link(node: Link) → None

Render a Link node.

Parameters:: node (Link) – Link to render

visit_image(node: Image) → None

Render an Image node.

Parameters:: node (Image) – Image to render

visit_line_break(node: LineBreak) → None

Render a LineBreak node.

Parameters:: node (LineBreak) – Line break to render

visit_strikethrough(node: Strikethrough) → None

Render a Strikethrough node.

Parameters:: node (Strikethrough) – Strikethrough to render

visit_mark(node: Mark) → None

Render a Mark (highlight) node.

Emits ==text== on flavors that support highlighting; otherwise falls back according to unsupported_inline_mode (plain text, forced == syntax, or an HTML <mark> tag).

Parameters:: node (Mark) – Mark to render

visit_underline(node: Underline) → None

Render an Underline node.

Parameters:: node (Underline) – Underline to render

visit_superscript(node: Superscript) → None

Render a Superscript node.

Parameters:: node (Superscript) – Superscript to render

visit_subscript(node: Subscript) → None

Render a Subscript node.

Parameters:: node (Subscript) – Subscript to render

visit_html_inline(node: HTMLInline) → None

Render an HTMLInline node.

Parameters:: node (HTMLInline) – Inline HTML to render

visit_comment_inline(node: CommentInline) → None

Render a CommentInline node (inline).

Parameters:: node (CommentInline) – Inline comment to render

visit_footnote_reference(node: FootnoteReference) → None

Render a FootnoteReference node.

Parameters:: node (FootnoteReference) – Footnote reference to render

visit_math_inline(node: MathInline) → None

Render a MathInline node.

Parameters:: node (MathInline) – Inline math to render

visit_footnote_definition(node: FootnoteDefinition) → None

Render a FootnoteDefinition node.

Parameters:: node (FootnoteDefinition) – Footnote definition to render

visit_definition_list(node: DefinitionList) → None

Render a DefinitionList node.

Parameters:: node (DefinitionList) – Definition list to render

visit_definition_term(node: DefinitionTerm) → None

Render a DefinitionTerm node.

Parameters:: node (DefinitionTerm) – Definition term to render

visit_definition_description(node: DefinitionDescription) → None

Render a DefinitionDescription node.

Parameters:: node (DefinitionDescription) – Definition description to render

visit_math_block(node: MathBlock) → None

Render a MathBlock node.

Parameters:: node (MathBlock) – Math block to render

render(doc: Document, output: str | Path | IO[bytes]) → None

Render AST to markdown and write to output.

Parameters:

doc (Document) – AST Document node to render
output (str, Path, or IO[bytes]) – Output destination (file path or file-like object)