all2md.ast.nodes

AST node classes for document representation.

This module defines the complete node hierarchy for representing markdown documents as Abstract Syntax Trees. Each node represents a structural or inline element in the document.

The node hierarchy is designed to: - Support all CommonMark elements plus common extensions - Enable multiple rendering strategies via visitor pattern - Preserve source information for debugging - Allow format-specific metadata attachment

Node Hierarchy

All nodes inherit from the base Node class and support the visitor pattern.

Block-level nodes represent structural document elements:

Document, Heading, Paragraph, CodeBlock, BlockQuote
List, ListItem, Table, TableRow, TableCell
ThematicBreak, HTMLBlock, Comment
FootnoteDefinition, DefinitionList, MathBlock

Inline nodes represent text formatting:

Text, Emphasis, Strong, Code
Link, Image, LineBreak
Strikethrough, Underline, Superscript, Subscript
HTMLInline, CommentInline
FootnoteReference, MathInline

class all2md.ast.nodes.SourceLocation

Bases: object

Source location information for AST nodes.

Preserves information about where a node originated in the source document, useful for debugging, error messages, and round-trip conversions.

Parameters:

format (str) – Source format (e.g., ‘pdf’, ‘html’, ‘docx’)
page (int or None, default = None) – Page number in source document (for paginated formats)
line (int or None, default = None) – Line number in source document (for text formats)
column (int or None, default = None) – Column number in source document
element_id (str or None, default = None) – Source element identifier (e.g., HTML element ID)
metadata (dict, default = empty dict) – Additional format-specific location information

format: str

page: int | None = None

line: int | None = None

column: int | None = None

element_id: str | None = None

metadata: dict[str, Any]

__init__(format: str, page: int | None = None, line: int | None = None, column: int | None = None, element_id: str | None = None, metadata: dict[str, ~typing.Any]=<factory>) → None

class all2md.ast.nodes.Node

Bases: ABC

Base class for all AST nodes.

All document nodes inherit from this base class and support the visitor pattern for traversal and rendering.

Parameters:

metadata (dict, default = empty dict) – Arbitrary metadata associated with this node
source_location (SourceLocation or None, default = None) – Information about where this node came from in the source

metadata: dict[str, Any]

source_location: SourceLocation | None

abstractmethod accept(visitor: Any) → Any

Accept a visitor for processing this node.

Parameters:: visitor (Any) – A visitor object with visit_* methods
Returns:: Result from the visitor’s processing
Return type:: Any

class all2md.ast.nodes.Document

Bases: Node

Root document node containing all other nodes.

The Document node represents the complete document and contains a list of block-level children.

Parameters:

children (list of Node, default = empty list) – Block-level nodes in the document
metadata (dict, default = empty dict) – Document-level metadata (title, author, etc.)
source_location (SourceLocation or None, default = None) – Source location information

children: list[Node]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this document.

Parameters:: visitor (Any) – A visitor object with visit_document method
Returns:: Result from visitor.visit_document(self)
Return type:: Any

add_section_after(target: str | int, new_section: Section | Document, case_sensitive: bool = False) → Document

Add a new section after the specified target section.

Parameters:

target (str or int) – Heading text or section index to insert after
new_section (Section or Document) – Section or document to insert
case_sensitive (bool, default = False) – Whether text matching is case-sensitive (for string targets)

Returns:

New document with the section inserted

Return type:

Document

Raises:

ValueError – If target section is not found

Examples

>>> from all2md.ast.sections import Section
>>> from all2md.ast.nodes import Heading, Paragraph, Text
>>> new_section = Section(
...     heading=Heading(level=2, content=[Text("New Section")]),
...     content=[Paragraph(content=[Text("Content")])],
...     level=2, start_index=0, end_index=0
... )
>>> updated_doc = doc.add_section_after("Introduction", new_section)

add_section_before(target: str | int, new_section: Section | Document, case_sensitive: bool = False) → Document

Add a new section before the specified target section.

Parameters:

target (str or int) – Heading text or section index to insert before
new_section (Section or Document) – Section or document to insert
case_sensitive (bool, default = False) – Whether text matching is case-sensitive (for string targets)

Returns:

New document with the section inserted

Return type:

Document

Raises:

ValueError – If target section is not found

Examples

>>> from all2md.ast.sections import Section
>>> from all2md.ast.nodes import Heading, Paragraph, Text
>>> new_section = Section(
...     heading=Heading(level=2, content=[Text("Preface")]),
...     content=[Paragraph(content=[Text("Introduction text")])],
...     level=2, start_index=0, end_index=0
... )
>>> updated_doc = doc.add_section_before("Chapter 1", new_section)

remove_section(target: str | int, case_sensitive: bool = False) → Document

Remove a section from the document.

Parameters:

target (str or int) – Heading text or section index to remove
case_sensitive (bool, default = False) – Whether text matching is case-sensitive (for string targets)

Returns:

New document with the section removed

Return type:

Document

Raises:

ValueError – If target section is not found

Examples

>>> updated_doc = doc.remove_section("Obsolete Section")
>>> updated_doc = doc.remove_section(2)  # Remove third section

replace_section(target: str | int, new_content: Section | Document | list[Node], case_sensitive: bool = False) → Document

Replace a section with new content.

Parameters:

target (str or int) – Heading text or section index to replace
new_content (Section, Document, or list of Node) – New content to replace the section with
case_sensitive (bool, default = False) – Whether text matching is case-sensitive (for string targets)

Returns:

New document with the section replaced

Return type:

Document

Raises:

ValueError – If target section is not found

Examples

Replace with a new section:

>>> from all2md.ast.sections import Section
>>> from all2md.ast.nodes import Heading, Paragraph, Text
>>> new_section = Section(
...     heading=Heading(level=2, content=[Text("Updated")]),
...     content=[Paragraph(content=[Text("New content")])],
...     level=2, start_index=0, end_index=0
... )
>>> updated_doc = doc.replace_section("Old Section", new_section)

Replace with custom nodes:

>>> new_nodes = [
...     Heading(level=2, content=[Text("New Heading")]),
...     Paragraph(content=[Text("Content here")])
... ]
>>> updated_doc = doc.replace_section(0, new_nodes)

insert_into_section(target: str | int, content: Node | list[Node], position: Literal['start', 'end', 'after_heading'] = 'end', case_sensitive: bool = False) → Document

Insert content into an existing section.

Parameters:

target (str or int) – Heading text or section index to insert into
content (Node or list of Node) – Content to insert
position ({"start", "end", "after_heading"}, default = "end") – Where to insert the content within the section
case_sensitive (bool, default = False) – Whether text matching is case-sensitive (for string targets)

Returns:

New document with content inserted

Return type:

Document

Raises:

ValueError – If target section is not found

Notes

“start”: Insert at the beginning of the section content (before all content)
“after_heading”: Insert immediately after the heading (same as “start”)
“end”: Insert at the end of the section content (after all content)

Examples

>>> from all2md.ast.nodes import Paragraph, Text
>>> new_para = Paragraph(content=[Text("Additional info")])
>>> updated_doc = doc.insert_into_section("Methods", new_para, position="end")

__init__(children: list[Node] = <factory>, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.Heading

Bases: Node

Heading node (h1-h6).

Represents a document heading with a level from 1 to 6 and inline content.

Parameters:

level (int) – Heading level (1-6, where 1 is most important)
content (list of Node, default = empty list) – Inline nodes representing heading text
metadata (dict, default = empty dict) – Heading metadata
source_location (SourceLocation or None, default = None) – Source location information

level: int

content: list[Node]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this heading.

Parameters:: visitor (Any) – A visitor object with visit_heading method
Returns:: Result from visitor.visit_heading(self)
Return type:: Any

__init__(level: int, content: list[Node] = <factory>, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.Paragraph

Bases: Node

Paragraph node containing inline content.

Represents a paragraph of text with inline formatting.

Parameters:

content (list of Node, default = empty list) – Inline nodes representing paragraph content
metadata (dict, default = empty dict) – Paragraph metadata
source_location (SourceLocation or None, default = None) – Source location information

content: list[Node]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this paragraph.

Parameters:: visitor (Any) – A visitor object with visit_paragraph method
Returns:: Result from visitor.visit_paragraph(self)
Return type:: Any

__init__(content: list[Node] = <factory>, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.CodeBlock

Bases: Node

Code block node with optional language specification.

Represents a fenced or indented code block.

Parameters:

content (str) – Code content (not parsed as markdown)
language (str or None, default = None) – Programming language for syntax highlighting
fence_char (str, default = '`') – Character used for fencing (` or ~)
fence_length (int, default = 3) – Number of fence characters
metadata (dict, default = empty dict) – Code block metadata
source_location (SourceLocation or None, default = None) – Source location information

content: str

language: str | None = None

fence_char: str = '`'

fence_length: int = 3

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this code block.

Parameters:: visitor (Any) – A visitor object with visit_code_block method
Returns:: Result from visitor.visit_code_block(self)
Return type:: Any

__init__(content: str, language: str | None = None, fence_char: str = '`', fence_length: int = 3, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.BlockQuote

Bases: Node

Block quote node containing other block elements.

Represents a quoted section of content.

Parameters:

children (list of Node, default = empty list) – Block-level nodes in the quote
metadata (dict, default = empty dict) – Block quote metadata
source_location (SourceLocation or None, default = None) – Source location information

children: list[Node]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this block quote.

Parameters:: visitor (Any) – A visitor object with visit_block_quote method
Returns:: Result from visitor.visit_block_quote(self)
Return type:: Any

__init__(children: list[Node] = <factory>, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.List

Bases: Node

List node (ordered or unordered).

Represents an ordered (numbered) or unordered (bulleted) list.

Parameters:

ordered (bool) – True for ordered lists, False for unordered
items (list of ListItem, default = empty list) – List items
start (int, default = 1) – Starting number for ordered lists
tight (bool, default = True) – Whether list is tight (no blank lines between items)
metadata (dict, default = empty dict) – List metadata
source_location (SourceLocation or None, default = None) – Source location information

ordered: bool

items: list[ListItem]

start: int = 1

tight: bool = True

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this list.

Parameters:: visitor (Any) – A visitor object with visit_list method
Returns:: Result from visitor.visit_list(self)
Return type:: Any

__init__(ordered: bool, items: list[ListItem] = <factory>, start: int = 1, tight: bool = True, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.ListItem

Bases: Node

List item node containing block content.

Represents a single item in a list, which can contain paragraphs, nested lists, or other block elements.

Parameters:

children (list of Node, default = empty list) – Block-level nodes in the list item
task_status ({'checked', 'unchecked'} or None, default = None) – For task lists (GFM extension)
metadata (dict, default = empty dict) – List item metadata
source_location (SourceLocation or None, default = None) – Source location information

children: list[Node]

task_status: Literal['checked', 'unchecked'] | None = None

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this list item.

Parameters:: visitor (Any) – A visitor object with visit_list_item method
Returns:: Result from visitor.visit_list_item(self)
Return type:: Any

__init__(children: list[Node] = <factory>, task_status: Literal['checked', 'unchecked'] | None=None, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.Table

Bases: Node

Table node with optional header and alignment.

Represents a table structure (GFM extension).

Parameters:

rows (list of TableRow, default = empty list) – Table rows (excluding header)
header (TableRow or None, default = None) – Optional header row
alignments (list, default = empty list) – Column alignments (‘left’, ‘center’, ‘right’, or None)
caption (str or None, default = None) – Optional table caption
metadata (dict, default = empty dict) – Table metadata
source_location (SourceLocation or None, default = None) – Source location information

rows: list[TableRow]

header: TableRow | None = None

alignments: list[Literal['left', 'center', 'right'] | None]

caption: str | None = None

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this table.

Parameters:: visitor (Any) – A visitor object with visit_table method
Returns:: Result from visitor.visit_table(self)
Return type:: Any

__init__(rows: list[TableRow] = <factory>, header: TableRow | None = None, alignments: list[~typing.Literal['left', 'center', 'right'] | None]=<factory>, caption: str | None = None, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.TableRow

Bases: Node

Table row node containing cells.

Represents a single row in a table.

Parameters:

cells (list of TableCell, default = empty list) – Cells in this row
is_header (bool, default = False) – Whether this is a header row
metadata (dict, default = empty dict) – Row metadata
source_location (SourceLocation or None, default = None) – Source location information

cells: list[TableCell]

is_header: bool = False

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this table row.

Parameters:: visitor (Any) – A visitor object with visit_table_row method
Returns:: Result from visitor.visit_table_row(self)
Return type:: Any

__init__(cells: list[TableCell] = <factory>, is_header: bool = False, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.TableCell

Bases: Node

Table cell node with optional span and alignment.

Represents a single cell in a table.

Parameters:

content (list of Node, default = empty list) – Inline content of the cell
colspan (int, default = 1) – Number of columns this cell spans
rowspan (int, default = 1) – Number of rows this cell spans
alignment ({'left', 'center', 'right'} or None, default = None) – Cell alignment
metadata (dict, default = empty dict) – Cell metadata
source_location (SourceLocation or None, default = None) – Source location information

content: list[Node]

colspan: int = 1

rowspan: int = 1

alignment: Literal['left', 'center', 'right'] | None = None

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this table cell.

Parameters:: visitor (Any) – A visitor object with visit_table_cell method
Returns:: Result from visitor.visit_table_cell(self)
Return type:: Any

__init__(content: list[Node] = <factory>, colspan: int = 1, rowspan: int = 1, alignment: Literal['left', 'center', 'right'] | None=None, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.ThematicBreak

Bases: Node

Thematic break node (horizontal rule).

Represents a thematic break/horizontal rule.

Parameters:

metadata (dict, default = empty dict) – Break metadata
source_location (SourceLocation or None, default = None) – Source location information

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this thematic break.

Parameters:: visitor (Any) – A visitor object with visit_thematic_break method
Returns:: Result from visitor.visit_thematic_break(self)
Return type:: Any

__init__(metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.HTMLBlock

Bases: Node

Raw HTML block node.

Represents a block of raw HTML content. This node preserves HTML as-is without modification or sanitization.

Parameters:

content (str) – Raw HTML content
metadata (dict, default = empty dict) – HTML block metadata
source_location (SourceLocation or None, default = None) – Source location information

Warning

Security: Raw HTML content is preserved without sanitization. Renderers MUST sanitize user-provided HTML content before rendering to prevent XSS attacks and other security vulnerabilities. For strict security contexts, consider using ValidationVisitor with allow_raw_html=False to reject documents containing raw HTML.

See also

ValidationVisitor: AST validator with optional HTML rejection

content: str

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this inline HTML.

Parameters:: visitor (Any) – A visitor object with visit_html_inline method
Returns:: Result from visitor.visit_html_inline(self)
Return type:: Any

__init__(content: str, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.FootnoteReference

Bases: Node

Footnote reference node (inline).

Represents an inline reference to a footnote, typically rendered as [^id]. This is used with flavors that support footnotes (e.g., MultiMarkdown, Pandoc).

Parameters:

identifier (str) – Footnote identifier (e.g., “1”, “note1”)
metadata (dict, default = empty dict) – Footnote reference metadata
source_location (SourceLocation or None, default = None) – Source location information

identifier: str

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this footnote reference.

Parameters:: visitor (Any) – A visitor object with visit_footnote_reference method
Returns:: Result from visitor.visit_footnote_reference(self)
Return type:: Any

__init__(identifier: str, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.MathInline

Bases: Node

Inline math node.

Represents inline mathematical content, typically rendered with $ delimiters. Supported by GFM, Pandoc, Kramdown, and MarkdownPlus flavors.

Parameters:

content (str) – LaTeX math content (without delimiters)
notation ({"latex", "mathml", "html"}, default "latex") – Format of the primary math representation stored in content.
representations (dict, default = empty dict) – Additional representations keyed by notation. The primary notation is automatically registered when missing.
metadata (dict, default = empty dict) – Math metadata
source_location (SourceLocation or None, default = None) – Source location information

content: str

notation: Literal['latex', 'mathml', 'html'] = 'latex'

representations: dict[Literal['latex', 'mathml', 'html'], str]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this inline math.

Parameters:: visitor (Any) – A visitor object with visit_math_inline method
Returns:: Result from visitor.visit_math_inline(self)
Return type:: Any

get_preferred_representation(preferred: Literal['latex', 'mathml', 'html']) → tuple[str, Literal['latex', 'mathml', 'html']]

Return math content for the requested representation with fallback.

Parameters:: preferred ({"latex", "mathml", "html"}) – Requested representation for rendering
Returns:: Math content and notation actually provided
Return type:: tuple[str, MathNotation]

__init__(content: str, notation: ~typing.Literal['latex', 'mathml', 'html'] = 'latex', representations: dict[~typing.Literal['latex', 'mathml', 'html'], str] = <factory>, metadata: dict[str, ~typing.Any] = <factory>, source_location: ~all2md.ast.nodes.SourceLocation | None = None) → None

class all2md.ast.nodes.CommentInline

Bases: Node

Inline comment node.

Represents an inline comment that appears within the text flow. Comments can originate from HTML comments, DOCX reviewer comments, or other format-specific comment mechanisms.

The node uses metadata to store variant information such as comment type, author, date, identifier, and other format-specific attributes.

Parameters:

content (str) – Comment text content
metadata (dict, default = empty dict) – Comment metadata. Common metadata keys: - ‘comment_type’: str - Type of comment (‘html’, ‘docx_review’, ‘latex’, ‘code’, ‘generic’) - ‘author’: str - Comment author name - ‘date’: str - Comment timestamp - ‘identifier’: str - Comment ID for linking/referencing - ‘label’: str - Comment label/number - ‘range_start’: str - Start of commented text range - ‘range_end’: str - End of commented text range
source_location (SourceLocation or None, default = None) – Source location information

Examples

HTML comment:

>>> CommentInline(
...     content="TODO: Fix this logic",
...     metadata={'comment_type': 'html'}
... )

DOCX reviewer comment:

>>> CommentInline(
...     content="This needs clarification",
...     metadata={
...         'comment_type': 'docx_review',
...         'author': 'John Doe',
...         'date': '2025-01-20',
...         'identifier': 'comment1'
...     }
... )

content: str

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this inline comment.

Parameters:: visitor (Any) – A visitor object with visit_comment_inline method
Returns:: Result from visitor.visit_comment_inline(self)
Return type:: Any

__init__(content: str, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.FootnoteDefinition

Bases: Node

Footnote definition node (block).

Represents a footnote definition, typically rendered as [^id]: content. Used with MultiMarkdown, Pandoc, Kramdown, and MarkdownPlus flavors.

Parameters:

identifier (str) – Footnote identifier matching a FootnoteReference
content (list of Node, default = empty list) – Block-level content of the footnote
metadata (dict, default = empty dict) – Footnote definition metadata
source_location (SourceLocation or None, default = None) – Source location information

identifier: str

content: list[Node]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this footnote definition.

Parameters:: visitor (Any) – A visitor object with visit_footnote_definition method
Returns:: Result from visitor.visit_footnote_definition(self)
Return type:: Any

__init__(identifier: str, content: list[Node] = <factory>, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.DefinitionList

Bases: Node

Definition list node (block).

Represents a definition list containing terms and their descriptions. Supported by MultiMarkdown, Pandoc, Kramdown, and MarkdownPlus flavors.

Parameters:

items (list of tuple, default = empty list) – List of (DefinitionTerm, list[DefinitionDescription]) tuples
metadata (dict, default = empty dict) – Definition list metadata
source_location (SourceLocation or None, default = None) – Source location information

items: list[tuple[DefinitionTerm, list[DefinitionDescription]]]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this definition list.

Parameters:: visitor (Any) – A visitor object with visit_definition_list method
Returns:: Result from visitor.visit_definition_list(self)
Return type:: Any

__init__(items: list[tuple[~all2md.ast.nodes.DefinitionTerm, list[~all2md.ast.nodes.DefinitionDescription]]]=<factory>, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.DefinitionTerm

Bases: Node

Definition term node (block).

Represents a term in a definition list.

Parameters:

content (list of Node, default = empty list) – Inline content of the term
metadata (dict, default = empty dict) – Term metadata
source_location (SourceLocation or None, default = None) – Source location information

content: list[Node]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this definition term.

Parameters:: visitor (Any) – A visitor object with visit_definition_term method
Returns:: Result from visitor.visit_definition_term(self)
Return type:: Any

__init__(content: list[Node] = <factory>, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.DefinitionDescription

Bases: Node

Definition description node (block).

Represents a description/definition in a definition list.

Parameters:

content (list of Node, default = empty list) – Block-level content of the description
metadata (dict, default = empty dict) – Description metadata
source_location (SourceLocation or None, default = None) – Source location information

content: list[Node]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this definition description.

Parameters:: visitor (Any) – A visitor object with visit_definition_description method
Returns:: Result from visitor.visit_definition_description(self)
Return type:: Any

__init__(content: list[Node] = <factory>, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

class all2md.ast.nodes.MathBlock

Bases: Node

Math block node.

Represents a block of mathematical content, typically rendered with $$ delimiters. Supported by GFM, MultiMarkdown, Pandoc, Kramdown, and MarkdownPlus flavors.

Parameters:

content (str) – LaTeX math content (without delimiters)
notation ({"latex", "mathml", "html"}, default "latex") – Format of the primary math representation stored in content.
representations (dict, default = empty dict) – Additional representations keyed by notation. The primary notation is automatically registered when missing.
metadata (dict, default = empty dict) – Math block metadata
source_location (SourceLocation or None, default = None) – Source location information

content: str

notation: Literal['latex', 'mathml', 'html'] = 'latex'

representations: dict[Literal['latex', 'mathml', 'html'], str]

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this math block.

Parameters:: visitor (Any) – A visitor object with visit_math_block method
Returns:: Result from visitor.visit_math_block(self)
Return type:: Any

get_preferred_representation(preferred: Literal['latex', 'mathml', 'html']) → tuple[str, Literal['latex', 'mathml', 'html']]: Return math content for the requested representation with fallback.

__init__(content: str, notation: ~typing.Literal['latex', 'mathml', 'html'] = 'latex', representations: dict[~typing.Literal['latex', 'mathml', 'html'], str] = <factory>, metadata: dict[str, ~typing.Any] = <factory>, source_location: ~all2md.ast.nodes.SourceLocation | None = None) → None

class all2md.ast.nodes.Comment

Bases: Node

Block-level comment node.

Represents a standalone comment block that appears at the block level. Comments can originate from HTML comments, LaTeX comments, code comments, or other format-specific comment mechanisms.

The node uses metadata to store variant information such as comment type, author, date, identifier, and other format-specific attributes.

Parameters:

content (str) – Comment text content
metadata (dict, default = empty dict) – Comment metadata. Common metadata keys: - ‘comment_type’: str - Type of comment (‘html’, ‘docx_review’, ‘latex’, ‘code’, ‘generic’) - ‘author’: str - Comment author name - ‘date’: str - Comment timestamp - ‘identifier’: str - Comment ID for linking/referencing - ‘label’: str - Comment label/number - ‘range_start’: str - Start of commented text range - ‘range_end’: str - End of commented text range
source_location (SourceLocation or None, default = None) – Source location information

Examples

HTML block comment:

>>> Comment(
...     content="This section needs review",
...     metadata={'comment_type': 'html'}
... )

DOCX reviewer comment at document end:

>>> Comment(
...     content="Please verify these numbers",
...     metadata={
...         'comment_type': 'docx_review',
...         'author': 'Jane Smith',
...         'date': '2025-01-20',
...         'identifier': 'comment2',
...         'label': '2'
...     }
... )

LaTeX comment:

>>> Comment(
...     content="TODO: Add more examples here",
...     metadata={'comment_type': 'latex'}
... )

content: str

metadata: dict[str, Any]

source_location: SourceLocation | None = None

accept(visitor: Any) → Any

Accept a visitor for processing this comment block.

Parameters:: visitor (Any) – A visitor object with visit_comment method
Returns:: Result from visitor.visit_comment(self)
Return type:: Any

__init__(content: str, metadata: dict[str, ~typing.Any]=<factory>, source_location: SourceLocation | None = None) → None

all2md.ast.nodes.get_node_children(node: Node) → list[Node]

Get all child nodes from a node.

This is a helper function for visitor pattern implementations that need to traverse the AST. It returns a list of all child nodes regardless of the node type.

Parameters:: node (Node) – The node to get children from
Returns:: List of child nodes (empty list if node has no children)
Return type:: list of Node

Examples

>>> heading = Heading(level=1, content=[Text("Hello"), Strong(content=[Text("world")])])
>>> children = get_node_children(heading)
>>> len(children)
2

all2md.ast.nodes.replace_node_children(node: Node, new_children: list[Node]) → Node

Create a copy of a node with replaced children.

This is a helper function for transformer pattern implementations. It creates a new node of the same type with the children replaced.

Parameters:

node (Node) – The node to copy and modify
new_children (list of Node) – New children to use in the copy

Returns:

New node with replaced children

Return type:

Node

Raises:

ValueError – If the node type doesn’t support children, if children are of the wrong type, or if the structure is invalid

Notes

Special handling for Table nodes:

The function inspects new_children to determine header vs body rows. The first TableRow with is_header=True becomes the table header. All other rows become body rows. This allows: - Adding a header: Include a TableRow with is_header=True - Removing a header: Omit rows with is_header=True - Preserving structure: Set is_header appropriately on rows

All new_children must be TableRow instances, or ValueError is raised.

Examples

Replace heading content:

>>> heading = Heading(level=1, content=[Text("Hello")])
>>> new_heading = replace_node_children(heading, [Text("Goodbye")])
>>> new_heading.content[0].content
'Goodbye'

Add header to table:

>>> table = Table(rows=[TableRow(cells=[...], is_header=False)])
>>> header = TableRow(cells=[...], is_header=True)
>>> new_table = replace_node_children(table, [header] + table.rows)
>>> new_table.header is not None
True