all2md.options.jinja

Configuration options for Jinja2 template-based rendering.

This module defines options for rendering AST documents using custom Jinja2 templates, enabling users to create arbitrary text-based output formats.

class all2md.options.jinja.JinjaRendererOptions

Bases: BaseRendererOptions

Configuration options for Jinja2 template-based rendering.

This dataclass contains settings for rendering AST documents using custom Jinja2 templates. Templates have full access to the document AST and can produce any text-based output format (XML, YAML, custom markup, etc.).

Parameters:

  • template_file (str or None, default None) – Path to Jinja2 template file. Either template_file or template_string must be provided.

  • template_string (str or None, default None) – Inline Jinja2 template as a string. Either template_file or template_string must be provided. If both are provided, template_file takes precedence.

  • template_dir (str or None, default None) – Directory for template includes and extends. If None and template_file is provided, uses the directory containing template_file. Required when using template_string with includes/extends.

  • escape_strategy ({"xml", "html", "latex", "yaml", "markdown", "none", "custom"} or None, default None) – Default escaping strategy for the output format: - “xml”: XML/HTML entity escaping - “html”: Same as xml - “latex”: LaTeX special character escaping - “yaml”: YAML string escaping - “markdown”: Markdown special character escaping - “none”: No escaping - “custom”: Use custom_escape_function - None: No default strategy (templates must handle escaping explicitly) This affects the default |render filter behavior.

  • custom_escape_function (Callable[[str], str] or None, default None) – Custom escape function when escape_strategy=”custom”. Function signature: (text: str) -> str

  • autoescape (bool, default False) – Enable Jinja2 autoescape for the template environment. When True, uses the escape_strategy for automatic escaping. Default is False to give templates full control.

  • enable_render_filter (bool, default True) – Enable the render filter for rendering nodes with default logic. When enabled, templates can use {{ node|render }} for convenience.

  • enable_escape_filters (bool, default True) – Enable format-specific escape filters (escape_xml, escape_latex, etc.). When enabled, templates can use {{ text|escape_xml }}.

  • enable_traversal_helpers (bool, default True) – Enable AST traversal helper functions (get_headings, get_links, etc.). When enabled, templates can use {{ get_headings(document) }}.

  • default_render_format ({"markdown", "plain", "html"}, default "markdown") – Default format for the render filter when no escape_strategy is set. Determines how nodes are rendered when using {{ node|render }}.

  • extra_context (dict[str, Any] or None, default None) – Additional context variables to make available in templates. These will be merged into the template context.

  • strict_undefined (bool, default True) – Raise errors for undefined variables in templates (Jinja2 StrictUndefined). When False, undefined variables render as empty strings.

Examples

Render using a template file:
>>> from all2md.options import JinjaRendererOptions
>>> options = JinjaRendererOptions(
...     template_file="templates/docbook.xml.jinja2",
...     escape_strategy="xml"
... )
Render using an inline template string:
>>> template = '''
... <doc>
... {% for node in document.children -%}
...   {{ node|render }}
... {%- endfor %}
... </doc>
... '''
>>> options = JinjaRendererOptions(
...     template_string=template,
...     escape_strategy="xml"
... )
Use custom escape function:
>>> def my_escape(text: str) -> str:
...     return text.replace("&", "&amp;")
>>> options = JinjaRendererOptions(
...     template_file="custom.jinja2",
...     escape_strategy="custom",
...     custom_escape_function=my_escape
... )
Add extra context variables:
>>> options = JinjaRendererOptions(
...     template_file="report.jinja2",
...     extra_context={"version": "1.0", "author": "Tool"}
... )

Notes

Templates receive the following context: - document: The Document node (typed AST object) - ast: The document as a dictionary (template-friendly) - metadata: Document metadata dictionary - title: Document title (metadata.get(“title”, “”)) - headings: List of all headings (if enable_traversal_helpers=True) - links: List of all links (if enable_traversal_helpers=True) - images: List of all images (if enable_traversal_helpers=True) - footnotes: List of all footnote definitions (if enable_traversal_helpers=True) - Any keys from extra_context

Available filters (if enabled):

  • render: Render a node with default logic

  • render_inline: Render inline content

  • to_dict: Convert Node to dictionary

  • escape_xml, escape_html: XML/HTML escaping

  • escape_latex: LaTeX escaping

  • escape_yaml: YAML escaping

  • escape_markdown: Markdown escaping

  • node_type: Get node type name as string

Available functions (if enabled): - get_headings(doc): Extract all heading nodes - get_links(doc): Extract all link nodes - get_images(doc): Extract all image nodes - get_footnotes(doc): Extract all footnote definitions - find_nodes(doc, node_type): Find all nodes of specified type - filter_nodes(doc, predicate): Filter nodes by custom predicate

template_file: str | None = None
template_string: str | None = None
template_dir: str | None = None
escape_strategy: Literal['xml', 'html', 'latex', 'yaml', 'markdown', 'none', 'custom'] | None = None
custom_escape_function: Callable[[str], str] | None = None
autoescape: bool = False
enable_render_filter: bool = True
enable_escape_filters: bool = True
enable_traversal_helpers: bool = True
default_render_format: Literal['markdown', 'plain', 'html'] = 'markdown'
extra_context: dict[str, Any] | None = None
strict_undefined: bool = True
__init__(fail_on_resource_errors: bool = False, max_asset_size_bytes: int = 52428800, metadata_policy: MetadataRenderPolicy = <factory>, creator: str | None = 'all2md', template_file: str | None = None, template_string: str | None = None, template_dir: str | None = None, escape_strategy: JinjaEscapeStrategy | None = None, custom_escape_function: Callable[[str], str] | None = None, autoescape: bool = False, enable_render_filter: bool = True, enable_escape_filters: bool = True, enable_traversal_helpers: bool = True, default_render_format: JinjaRenderFormat = 'markdown', extra_context: dict[str, Any] | None = None, strict_undefined: bool = True) → None