Renderer: AST to MyST Markdown Rendering#

Renderer maps the token types produced by Parser back to normalized MyST text: directives with cleaned options and de-duplicated attributes, roles, math, targets, comments, and block breaks. Rendering functions self-register into REGISTRY via the register() decorator, and inter-block spacing is decided by the Spacer policies installed in setup().

AST to MyST Markdown Rendering.

Renderer maps the token types produced by Parser back to normalized MyST text: directives with cleaned options and de-duplicated attributes, roles, math, targets, comments, and block breaks. Rendering functions self-register into REGISTRY via the register() decorator, and inter-block spacing is decided by the Spacer policies installed in setup().

class myform.Renderer.Attribute(*, key: str, val: str | int | float | bool)#

Represents an HTML attribute for rendering as an inline attribute.

class myform.Renderer.Renderer#

Renderer for MyST-specific syntax nodes (i.e. AST -> MD).

REGISTRY: ClassVar[dict[str, Interface]] = {'blockquote': <function Renderer.render_blockquote>, 'math_block': <function Renderer.render_math_block>, 'math_block_label': <function Renderer.render_math_block_label>, 'math_inline': <function Renderer.render_math_inline>, 'myst_block_break': <function Renderer.render_myst_block_break>, 'myst_directive': <function Renderer.render_myst_directive>, 'myst_ignored': <function Renderer.render_myst_ignored>, 'myst_line_comment': <function Renderer.render_myst_line_comment>, 'myst_role': <function Renderer.render_myst_role>, 'myst_target': <function Renderer.render_myst_target>, 'root': <function Renderer.render_root>}#

Populated by register()

static register(fn: Interface, name: str = '') → Interface#

Decorator to register a method as a renderer for a given node type.

classmethod render_directive_options(options: dict[str, Any], *, style: str = 'auto', yaml_threshold: int = 3) → str#

Render directive options.

Options definitions are the equivalent of python keyword parameters, providing the writer the opportunity to customize the directive’s output in various preset ways.

Parameters:

  • options – A map of option(/parameter) names to serializable values.

  • style – auto (prefix, escalating to a YAML block past yaml_threshold), prefix (always :key: val), or yaml (always a --- block). See MystOptions.directive_options_style.

  • yaml_threshold – In auto style, switch to a YAML block once the rendered options exceed this many lines.

Returns:

Formatted markdown content describing the given options.

classmethod render_attributes(attributes: list[tuple[str, Any]]) → str#

Transform HTML attributes into string-separated ‘inline attributes’.

classmethod render_blocks(*nodes: Node, ctx: Context) → str#

Render multiple block-level nodes with appropriate spacing.

classmethod render_block_spacing(nodes: tuple[Node, Node], texts: tuple[str, str], ctx: Context) → int#

Choose the vertical spacing between two adjacent blocks, consulting the spacers.

Parameters:

  • nodes – The pair of block-level nodes between which we are rendering a space.

  • texts – The rendered text of each node.

  • ctx – The render context, used to resolve the option-aware spacer set (_spacers).

Returns:

The number of newlines to insert between the two nodes (2, the default, when no spacer matches).

static render_myst_line_comment(node: Node, _: Context) → str#

Render line comment nodes.

static render_myst_block_break(node: Node, _: Context) → str#

Render block break nodes.

static render_myst_target(node: Node, _: Context) → str#

Render target anchors.

static render_myst_ignored(node: Node, _: Context) → str#

Emit a skip-formatting span’s captured source verbatim (see Ignore).

Unlike an html_block carrier – whose renderer calls lstrip on the first line and would silently de-indent a preserved code block – this returns the source untouched, so ignore comments truly preserve their span. Block spacing is added by the root joiner.

static render_math_inline(node: Node, _: Context) → str#

Render inline math.

static render_math_block(node: Node, ctx: Context) → str#

Render block math.

static render_math_block_label(node: Node, ctx: Context) → str#

Render block math with label.

static render_blockquote(node: Node, ctx: Context) → str#

Render blockquotes while being safe with math blocks inside.

static render_myst_role(node: Node, ctx: Context) → str#

Render inline role nodes.

static render_myst_directive(node: Node, ctx: Context) → str#

Render directives.

Copied from upstream mdformat core and should be kept up-to-date if upstream introduces changes. Note that only two lines are added to the upstream implementation, i.e. the condition that calls render_directive_content function.

static render_root(root: Node, ctx: Context) → str#

Render the root node by rendering all children with appropriate spacing.

Parameters:

  • root – The root node of the render tree.

  • ctx – The current render context.

Returns:

The fully rendered Markdown string.

classmethod prerender_root(root: Node, ctx: Context) → None#

Pre-render hook – make sure to call superclass’ version if you override it.

classmethod postrender_root(rendered_nodes: list[tuple[Node, str]], ctx: Context) → str#

Post-render hook – make sure to call superclass’ version if you override it.