all2md.renderers.org

Org-Mode rendering from AST.

This module provides the OrgRenderer class which converts AST nodes to Org-Mode text. The renderer supports configurable handling of TODO states, tags, and properties.

The rendering process uses the visitor pattern to traverse the AST and generate Org-Mode output.

class all2md.renderers.org.OrgRenderer

Bases: NodeVisitor, InlineContentMixin, BaseRenderer

Render AST nodes to Org-Mode.

This class implements the visitor pattern to traverse an AST and generate Org-Mode output with configurable formatting options.

Parameters:

options (OrgRendererOptions or None, default = None) – Org-Mode formatting options

Examples

Basic usage:

>>> from all2md.ast import Document, Heading, Text
>>> from all2md.renderers.org import OrgRenderer
>>> doc = Document(children=[
...     Heading(level=1, content=[Text(content="Title")])
... ])
>>> renderer = OrgRenderer()
>>> org = renderer.render_to_string(doc)
>>> print(org)
* Title

Rendering enhanced Org features:

>>> from all2md import to_markdown
>>> from all2md.options.org import OrgParserOptions, OrgRendererOptions
>>> # Parse with enhanced features
>>> parser_opts = OrgParserOptions(
...     parse_logbook=True,
...     parse_clock=True,
...     parse_closed=True,
...     preserve_timestamp_metadata=True
... )
>>> # Render with enhanced features
>>> renderer_opts = OrgRendererOptions(
...     preserve_logbook=True,
...     preserve_clock=True,
...     preserve_closed=True
... )
>>> # Round-trip conversion preserves these features
>>> markdown = to_markdown(
...     "orgfile.org",
...     source_format="org",
...     parser_options=parser_opts
... )

Notes

Enhanced Org-Mode Features:

The renderer can output enhanced Org-mode metadata including:

  • CLOSED timestamps: When tasks are completed (org_closed metadata)

  • SCHEDULED/DEADLINE: With repeaters and time ranges (org_scheduled, org_deadline metadata)

  • LOGBOOK drawer: State changes and notes (org_logbook metadata)

  • CLOCK entries: Time tracking entries (org_clock metadata)

  • Tags: Heading tags (tags metadata)

  • TODO states: Task states (todo_keyword metadata)

Metadata Format Compatibility:

The renderer handles both dictionary (new format) and string (legacy format) metadata for backward compatibility:

  • Dictionary format includes structured data (start date, repeater, etc.)

  • String format is rendered directly

  • This ensures existing AST structures continue to work

orgparse Parser Limitations:

When working with documents parsed by the OrgParser (which uses orgparse), be aware that some metadata may be incomplete:

  • LOGBOOK drawer content may be missing if SCHEDULED/DEADLINE are placed after PROPERTIES drawer (orgparse strips it)

  • CLOCK entries may be incomplete in nested sections

  • The renderer handles these gracefully by checking for None/empty values

For best results when round-tripping Org-mode documents, use standard Org-mode formatting (SCHEDULED/DEADLINE before PROPERTIES drawer).

Initialize the Org renderer with options.

__init__(options: OrgRendererOptions | None = None)

Initialize the Org renderer with options.

render_to_string(document: Document) → str

Render a document AST to Org-Mode string.

Parameters:

document (Document) – The document node to render

Returns:

Org-Mode 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.

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_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

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_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 inline HTML (preserve as-is).

visit_html_block(node: HTMLBlock) → None

Render HTML block (wrap in export block).

visit_footnote_reference(node: FootnoteReference) → None

Render footnote reference.

visit_footnote_definition(node: FootnoteDefinition) → None

Render footnote definition.

visit_math_inline(node: MathInline) → None

Render inline math.

visit_math_block(node: MathBlock) → None

Render math block.

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_comment(node: Comment) → None

Render a Comment node (block-level).

Parameters:

node (Comment) – Comment block to render

visit_comment_inline(node: CommentInline) → None

Render a CommentInline node (inline).

Parameters:

node (CommentInline) – Inline comment to render

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

Render AST to Org-Mode 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)