FLM Fragment Renderers flm.fragmentrenderer

Fragment renderers for producing FLM output in various formats.

Each renderer subclasses FragmentRenderer and implements the format-specific rendering methods.

Available renderers:

class flm.fragmentrenderer.FragmentRenderer(config=None)

Base class for defining how to render FLM content in a given output format.

Subclasses must implement the abstract render_* methods such as render_value(), render_text_format(), render_heading(), render_enumeration(), render_verbatim(), render_link(), etc.

The base class provides the rendering pipeline: it traverses the node tree, handles block/paragraph decomposition, manages delayed rendering, and dispatches to the appropriate render_* methods.

Parameters:

config – Optional dictionary of configuration options. Keys are set as attributes on the renderer instance (e.g., use_link_target_blank for HTML).

supports_delayed_render_markers = False

If True, then the render methods generate special-syntax placeholders for content whose rendering must be delayed (e.g., references to figures, etc.). If False, then the whole content must be rendered in two passes.

document_render_start(render_context)

Called by FLMDocument.render() at the start of the rendering pipeline, before the render callback is invoked. Override to initialise renderer-specific state in render_context.

Parameters:

render_context – The document render context for this render pass.

document_render_finish(render_context)

Called by FLMDocument.render() after the rendering pipeline is complete (including delayed-render resolution). Override to tear down renderer-specific state.

Parameters:

render_context – The document render context for this render pass.

render_fragment(flm_fragment, render_context, is_block_level=None)

Render an FLMFragment into the output format.

Parameters:

  • flm_fragment – The fragment to render.

  • render_context – The current render context.

  • is_block_level – Override the fragment’s block-level setting.

Returns:

The rendered output string.

render_nodelist(nodelist, render_context, is_block_level=None)

Render a node list, handling block-level decomposition.

If the node list contains block-level content (paragraphs, lists, figures), it is split into blocks and rendered via render_blocks(). Otherwise it is rendered as inline content via render_inline_content().

Parameters:

  • nodelist – A LatexNodeList with flm_is_block_level and (if block-level) flm_blocks attributes set by the FLM finalizer.

  • render_context – The current render context.

  • is_block_level – Override block-level detection. If None (the default), the node list’s own flm_is_block_level flag is used. If False and the node list contains block-level content, a ValueError is raised.

Returns:

The rendered output string.

render_node(node, render_context)

Render a single parsed node by dispatching to the appropriate render_node_* method based on the node type (chars, group, macro, environment, specials, math, or comment). If the node has an flm_replace_by_node attribute, that replacement node is rendered instead.

Parameters:

  • node – A pylatexenc node.

  • render_context – The current render context.

Returns:

The rendered output string for this node.

Raises:

ValueError – If the node type is not recognised.

render_node_chars(node, render_context)
render_node_comment(node, render_context)
render_node_group(node, render_context)
render_node_macro(node, render_context)
render_node_environment(node, render_context)
render_node_specials(node, render_context)
render_invocable_node(node, render_context)
render_invocable_node_call_render(node, flm_specinfo, render_context)
render_node_math(node, render_context)
render_math_content(delimiters, nodelist, render_context, displaytype, *, environmentname=None, target_id=None)
recompose_latex(node)

Recompose a node or nodelist back into its FLM/LaTeX source text.

Used internally when rendering math content verbatim.

Parameters:

node – A pylatexenc node or nodelist.

Returns:

The reconstructed FLM source string.

render_blocks(node_blocks, render_context)

Render a list of block-level items (paragraphs and standalone block nodes) and join them together.

Each block is either a LatexNodeList (rendered as a paragraph via render_build_paragraph()) or a single block-level node (rendered via render_node()). The results are joined with render_join_blocks().

Parameters:

  • node_blocks – A list of node lists or single block-level nodes.

  • render_context – The current render context.

Returns:

The rendered output string with all blocks joined.

render_build_paragraph(nodelist, render_context)

Render a node list as a single paragraph.

By default this delegates to render_inline_content(). Subclasses may override to wrap the result in paragraph markup (e.g., <p>...</p> in HTML).

Parameters:

  • nodelist – The node list forming one paragraph.

  • render_context – The current render context.

Returns:

The rendered paragraph string.

render_inline_content(nodelist, render_context)

Render all nodes in nodelist as inline content and join them.

Each node is rendered individually via render_node(), then the results are concatenated with render_join().

Parameters:

  • nodelist – The node list to render inline.

  • render_context – The current render context.

Returns:

The rendered inline content string.

render_join(content_list, render_context)

Join a list of already-rendered inline content strings.

The default implementation concatenates the strings with no separator.

Parameters:

  • content_list – List of rendered content strings.

  • render_context – The current render context.

Returns:

The concatenated result.

render_join_blocks(content_list, render_context)

Join a list of already-rendered block-level content strings.

Each element is a paragraph or standalone block. The default implementation joins non-empty items with a double newline.

Parameters:

  • content_list – List of rendered block strings (may contain None or empty strings, which are skipped).

  • render_context – The current render context.

Returns:

The joined result.

render_semantic_span(content, role, render_context, *, annotations=None, target_id=None)

Wrap inline content in a semantic span.

Marks the given already-rendered inline text as belonging to a single construct (e.g., a sequence of citations or endnotes). In HTML, this corresponds to a <span> tag.

The default implementation returns content unchanged.

Parameters:

  • content – The already-rendered inline content string.

  • role – A string identifying the semantic role (e.g., 'citations', 'footnotes').

  • render_context – The current render context.

  • annotations – Optional list of additional annotation strings.

  • target_id – Optional anchor ID for the element.

Returns:

The wrapped content string.

render_semantic_block(content, role, render_context, *, annotations=None, target_id=None)

Wrap block content in a semantic container.

Encloses the given already-rendered block in a semantic element (e.g., an HTML <section> or <div>) that conveys document structure without necessarily affecting visual layout.

The default implementation returns content unchanged.

Parameters:

  • content – The already-rendered block content string.

  • role – A string identifying the semantic role (e.g., 'section', 'enumeration').

  • render_context – The current render context.

  • annotations – Optional list of additional annotation strings.

  • target_id – Optional anchor ID for the element.

Returns:

The wrapped content string.

replace_delayed_markers_with_final_values(content, delayed_values)

Replace delayed-render markers in the output with final values.

Only used when supports_delayed_render_markers is True. After the first rendering pass, this method substitutes the placeholder markers (produced by render_delayed_marker()) with the actual rendered content.

Parameters:

  • content – The first-pass output string containing markers.

  • delayed_values – A dictionary mapping delayed keys to their final rendered content strings.

Returns:

The output string with all markers replaced.

render_value(value, render_context)

Render a plain text value, applying any format-specific escaping.

For example, the HTML renderer escapes <, >, and & characters. The plain text renderer returns value unchanged.

Parameters:

  • value – The raw text string to render.

  • render_context – The current render context.

Returns:

The escaped/formatted output string.

render_delayed_marker(node, delayed_key, render_context)

Return a placeholder marker for a delayed-render node.

Used when supports_delayed_render_markers is True. The marker is later replaced with the real content by replace_delayed_markers_with_final_values().

Parameters:

  • node – The delayed-render node.

  • delayed_key – The unique key identifying this delayed node.

  • render_context – The current render context.

Returns:

A marker string that will be substituted later.

render_delayed_dummy_placeholder(node, delayed_key, render_context)

Return a disposable placeholder for a delayed-render node.

Used on the first pass of a two-pass rendering scheme (when supports_delayed_render_markers is False). The returned value is discarded after the first pass and never appears in the final output.

Parameters:

  • node – The delayed-render node.

  • delayed_key – The unique key identifying this delayed node.

  • render_context – The current render context.

Returns:

A dummy placeholder string.

render_nothing(render_context, annotations=None)

Render an empty or invisible element.

May produce an empty string, an HTML comment, or another format-appropriate representation of “nothing”.

Parameters:

  • render_context – The current render context.

  • annotations – Optional list of annotation strings that describe the empty element (e.g., for debugging).

Returns:

A string representing empty content in the output format.

render_empty_error_placeholder(debug_str, render_context)

Render a placeholder indicating a rendering error.

Used when a construct could not be rendered properly. The output should be minimal and may include debug_str for diagnostics.

Parameters:

  • debug_str – A short description of the error for debugging.

  • render_context – The current render context.

Returns:

A placeholder string in the output format.

render_text_format(text_formats, nodelist, render_context)

Render text with formatting such as bold, italic, or code.

Parameters:

  • text_formats – A list of format name strings (e.g., ['textbf'], ['textit'], ['defterm-term']).

  • nodelist – The node list containing the formatted content.

  • render_context – The current render context.

Returns:

The rendered and formatted output string.

render_enumeration(iter_items_nodelists, counter_formatter, render_context, *, target_id_generator=None, annotations=None)

Render an enumeration (ordered or unordered list).

Parameters:

  • iter_items_nodelists – An iterable of node lists, one per list item.

  • counter_formatter – A callable counter_formatter(n) returning the formatted tag for item number n (1-based). Returns a string or a node list, or None for bullet lists.

  • render_context – The current render context.

  • target_id_generator – Optional callable target_id_generator(n) returning a target anchor ID for item n, or None.

  • annotations – Optional list of annotation strings.

Returns:

The rendered enumeration as a block-level string.

render_lines(lines_info_list, render_context, *, role=None, annotations=None, target_id=None)

Render a sequence of lines (e.g., from a lines environment).

Parameters:

  • lines_info_list – A list of line info objects, each having at least a nodelist attribute and optional indent_left, indent_right, and align attributes.

  • render_context – The current render context.

  • role – Optional semantic role string (e.g., 'lines').

  • annotations – Optional list of annotation strings.

  • target_id – Optional anchor ID for the block.

Returns:

The rendered lines as a string.

render_heading(heading_nodelist, render_context, *, heading_level=1, inline_heading=False, target_id=None, annotations=None)

Render a section heading.

Parameters:

  • heading_nodelist – The node list containing the heading text.

  • render_context – The current render context.

  • heading_level – Integer level (1–6) or the string 'theorem' for theorem-style headings.

  • inline_heading – If True, the heading is a run-in heading (e.g., \paragraph) that does not start a new block.

  • target_id – Optional anchor ID for the heading.

  • annotations – Optional list of annotation strings.

Returns:

The rendered heading string.

render_verbatim(value, render_context, *, is_block_level=False, annotations=None, target_id=None)

Render verbatim (pre-formatted) text, such as code or math source.

Parameters:

  • value – The raw verbatim text string.

  • render_context – The current render context.

  • is_block_level – True if the verbatim block should be rendered as a block-level element.

  • annotations – Optional list of annotation strings (e.g., ['verbatimcode'], ['inline-math']).

  • target_id – Optional anchor ID for the element.

Returns:

The rendered verbatim content string.

Render a hyperlink.

Parameters:

  • ref_type – The type of reference (e.g., 'href', 'url', 'ref').

  • href – The link target. Can be an external URL or an anchor fragment ('#fragment-name') for internal links.

  • display_nodelist – The node list for the displayed link text.

  • render_context – The current render context.

  • annotations – Optional list of annotation strings.

Returns:

The rendered hyperlink string.

render_annotation_comment(display_nodelist, render_context, is_block_level=False, color_index=0, initials=None)

Render an annotation comment (e.g., from \annot).

Parameters:

  • display_nodelist – The node list for the comment text.

  • render_context – The current render context.

  • is_block_level – Whether to render as a block element.

  • color_index – Integer selecting a color for the annotation.

  • initials – Optional string with the annotator’s initials.

Returns:

The rendered annotation comment string.

render_annotation_highlight(display_nodelist, render_context, is_block_level=False, color_index=0, initials=None)

Render an annotation highlight (e.g., from \annot).

Parameters:

  • display_nodelist – The node list for the highlighted text.

  • render_context – The current render context.

  • is_block_level – Whether to render as a block element.

  • color_index – Integer selecting a color for the highlight.

  • initials – Optional string with the annotator’s initials.

Returns:

The rendered annotation highlight string.

render_float(float_instance, render_context)

Render a float (figure, table, or other captioned block).

Parameters:

  • float_instance – A float instance object providing float_type_info, content_nodelist, caption_nodelist, counter_value, and formatted_counter_value_flm.

  • render_context – The current render context.

Returns:

The rendered float as a block-level string.

render_graphics_block(graphics_resource, render_context)

Render a graphics/image block.

Parameters:

  • graphics_resource – A graphics resource object with a src_url attribute pointing to the image source.

  • render_context – The current render context.

Returns:

The rendered graphics block string.

render_cells(cells_model, render_context, target_id=None)

Render a cells/table structure.

Parameters:

  • cells_model – A cells model object with cells_data (list of cell objects, each having content_nodes, styles, and placement) and cells_size.

  • render_context – The current render context.

  • target_id – Optional anchor ID for the table element.

Returns:

The rendered table/cells string.

ensure_render_context(render_context)

Return render_context if it is not None, otherwise create a minimal standalone FLMRenderContext.

Parameters:

render_context – An existing render context, or None.

Returns:

A valid FLMRenderContext.

HTML Renderer

class flm.fragmentrenderer.html.HtmlFragmentRenderer(config=None)

Fragment renderer that produces HTML output.

Renders FLM content as HTML strings. Supports delayed-render markers, MathJax-compatible math output, and configurable link behaviour.

Configuration attributes can be set via the config dictionary passed to the constructor or by setting them directly on the instance. See the class-level attribute documentation for available options.

Usually, links will never open in a new tab. Set this to True on a specific instance to add target="_blank" to links so that they open in a new tab. This never applies to anchor links, i.e., urls that begin with ‘#’.

Set this attribute to a callable to decide whether or not to set target=”_blank” on a per-URL basis. The callable accepts a single argument, the URL given as a string, and returns True (open in new tab) or False (don’t).

html_blocks_joiner: str = '\n'

Raw HTML string to insert between different blocks. By default, we use a simple newline to avoid having very long lines in the HTML code. For slightly smaller HTML code and if you don’t mind long lines, use an empty string here.

heading_tags_by_level: Mapping[int | str, str] = {'theorem': 'span', 1: 'h1', 2: 'h2', 3: 'h3', 4: 'span', 5: 'span', 6: 'span'}
inline_heading_add_space: bool = True

Whether or not to include a space after an inline (run-in) heading, e.g., for \paragraph. Visually, the space should be there, but removing it makes it much easier to control the space using CSS.

aggressively_escape_html_attributes: bool = False

If True, then values of HTML attributes, e.g., the URL in <a href="....">, are escaped as normal HTML with HTML entities like ‘&amp;’. The default setting, aggressively_escape_html_attributes=False, only escapes ‘”’ characters, and will escape an ‘&’ character only if it looks like part of an entity. I.e., ‘/page?a=1&b=2’ is not modified but ‘/page?a=1&b;3’ will become ‘/page?a=1&amp;b;3’.

Applying the general HTML escape mechanism to attribute values (setting aggressively_escape_html_attributes=True) can make them appear more obscure (e.g., the link to /page?a=1&b=2 becomes /page?a=1&amp;b=2). While this is correct HTML and works fine in probably all browsers of course, there might be some HTML parsers/skimmers that can choke on that syntax. So the default setting is aggressively_escape_html_attributes=False.

render_nothing_as_comment_with_annotations: bool = True
use_mathjax: bool = True
use_standard_math_delimiters: bool = True
include_node_data_attrs_fn: None | Callable[[Any], dict] = None

Will pin data attributes to HTML tags that are associated with FLM tree nodes. This works for certain tags that have a direct relationship to a specific node, such as a <p>...</p> block for a nodelist.

If non-None, this should be set to a callable that takes the node or nodelist as first positional argument. In the future I might add keyword arguments to provide extra information, so please accept **kwargs, too. The callable should return a dictionary of data attributes to set on the HTML tag. E.g.

def my_include_node_data_attrs_fn(node, **kwargs):
    if isinstance(node, LatexNodeList):
        # set data-list-length="<the nodelist length>" on the
        # <p> tag
        return { 'list-length': len(node.nodelist) }
    return None # returning None or {} does not set any additional attribs
verbatim_highlight_spaces: bool = False
verbatim_protect_backslashes: bool = True
lines_use_line_span: bool = True
lines_use_br: bool = True
lines_container_tag: Mapping[str, str] = {}
float_caption_title_separator: str = ': '
graphics_raster_magnification: int | float = 1
graphics_vector_magnification: int | float = 1
supports_delayed_render_markers = True

We use the marker <FLM:DLYD:delayed_key/> for delayed content, which cannot be confused with the rest of the HTML code that can be generated from this code generator.

Do not change this value.

htmlescape(value)

Escape a string for safe inclusion in HTML content.

Escapes <, >, &, and " via html.escape(), then replaces several Unicode space characters with their named HTML entities (e.g., non-breaking space, thin space, em space).

Parameters:

value – The raw text string.

Returns:

The HTML-escaped string.

htmlescape_double_quoted_attribute_value(value)
generate_open_tag(tagname, *, attrs=None, class_names=None, self_close_tag=False)

Generate an HTML opening tag string.

Parameters:

  • tagname – The HTML tag name (e.g., 'div', 'span').

  • attrs – Optional dictionary (or list of 2-tuples) of HTML attributes. Must not include 'class' – use class_names instead.

  • class_names – Optional list of CSS class name strings.

  • self_close_tag – If True, produce a self-closing tag (e.g., <br/>).

Returns:

The opening tag string (e.g., '<div class="foo">').

Raises:

ValueError – If attrs contains a 'class' key.

wrap_in_tag(tagname, content_html, *, attrs=None, class_names=None)

Wrap content in an HTML element.

Produces <tagname ...>content_html</tagname>.

Parameters:

  • tagname – The HTML tag name.

  • content_html – The already-escaped inner HTML string.

  • attrs – Optional dictionary of HTML attributes.

  • class_names – Optional list of CSS class name strings.

Returns:

The complete HTML element string.

Wrap content in an <a> hyperlink tag.

Respects the use_link_target_blank setting to conditionally add target="_blank" for external links.

Parameters:

  • display_html – The already-escaped inner HTML for the link.

  • target_href – The URL or anchor fragment. If falsy, defaults to '#'.

  • class_names – Optional list of CSS class name strings.

  • attrs – Optional dictionary of additional HTML attributes to set on the <a> tag.

Returns:

The complete <a>...</a> HTML string.

render_build_paragraph(nodelist, render_context)
render_inline_content(nodelist, render_context)
render_join(content_list, render_context)

Join together a collection of pieces of content that have already been rendered. Usually you’d want to simply join the strings together with no joiner, which is what the default implementation does.

render_join_blocks(content_list, render_context)

Join together a collection of pieces of content that have already been rendered. Each piece is itself a block of content, which can assumed to be at least paragraph-level or even semantic blocks. Usually you’d want to simply join the strings together with no joiner, which is what the default implementation does.

render_value(value, render_context)
render_empty_error_placeholder(debug_str, render_context)
render_nothing(render_context, annotations=None)
render_verbatim(value, render_context, *, is_block_level=False, annotations=None, target_id=None)
render_math_content(delimiters, nodelist, render_context, displaytype, environmentname=None, target_id=None)
render_text_format(text_formats, nodelist, render_context)
render_semantic_span(content, role, render_context, *, annotations=None, target_id=None)
render_semantic_block(content, role, render_context, *, annotations=None, target_id=None)
render_lines(lines_info_list, render_context, *, role=None, annotations=None, target_id=None)

Render a sequence of inline-content lines separated by line breaks. Collect the lines in a single block-level element. Suitable for typesetting a poem, addresses, or other pieces of text with specific line break requirements.

render_enumeration(iter_items_nodelists, counter_formatter, render_context, *, target_id_generator=None, annotations=None, nested_depth=None)

Render an enumeration as an HTML <dl> definition list.

Each item is wrapped in a <dt>/<dd> pair inside a <dl class="enumeration"> element.

Parameters:

  • iter_items_nodelists – An iterable of node lists, one per list item.

  • counter_formatter – A callable counter_formatter(n) returning the formatted tag for item number n (1-based). May return a string or a node list.

  • render_context – The current render context.

  • target_id_generator – Optional callable target_id_generator(n) that takes a 1-based item number and returns an anchor name to use as the id attribute on the <dt> element, or None if no anchor is needed.

  • annotations – Optional list of annotation strings added as CSS class names on the <dl> wrapper.

  • nested_depth – Optional nesting depth (unused in this renderer).

Returns:

The rendered enumeration as an HTML string.

render_heading(heading_nodelist, render_context, *, heading_level=1, inline_heading=False, target_id=None, annotations=None)
render_annotation_comment(display_nodelist, render_context, is_block_level=False, color_index=0, initials=None)
render_annotation_highlight(display_nodelist, render_context, is_block_level=False, color_index=0, initials=None)
render_delayed_marker(node, delayed_key, render_context)
render_delayed_dummy_placeholder(node, delayed_key, render_context)
replace_delayed_markers_with_final_values(content, delayed_values)
render_float(float_instance, render_context)
render_graphics_block(graphics_resource, render_context)
render_cells(cells_model, render_context, target_id=None)
class flm.fragmentrenderer.html.FragmentRendererInformation

Fragment renderer information for the flm.fragmentrenderer.html module.

FragmentRendererClass

alias of HtmlFragmentRenderer

static get_style_information(fragment_renderer)
format_name = 'html'

Text Renderer

class flm.fragmentrenderer.text.TextFragmentRenderer(config=None)

Fragment renderer that produces plain-text output.

Renders FLM content as plain Unicode text with no markup. Headings are underlined with ASCII characters, lists are indented, and links optionally include the URL in angle brackets.

Does not support delayed-render markers; a two-pass rendering scheme is used instead.

display_href_urls: bool = True
float_separator_top: str = '················································································'
float_separator_bottom: str = '················································································'
heading_level_formatter: Mapping[int | str, Callable[[str], str]] = {'theorem': <function TextFragmentRenderer.<lambda>>, 1: <function TextFragmentRenderer.<lambda>>, 2: <function TextFragmentRenderer.<lambda>>, 3: <function TextFragmentRenderer.<lambda>>, 4: <function TextFragmentRenderer.<lambda>>, 5: <function TextFragmentRenderer.<lambda>>, 6: <function TextFragmentRenderer.<lambda>>}
float_caption_title_separator: str = ': '
cells_column_sep: str = '   '
render_value(value, render_context)
render_delayed_marker(node, delayed_key, render_context)
render_delayed_dummy_placeholder(node, delayed_key, render_context)
render_nothing(render_context, annotations=None)
render_empty_error_placeholder(debug_str, render_context)
render_text_format(text_formats, nodelist, render_context)
render_lines(lines_info_list, render_context, *, role=None, annotations=None, target_id=None)
render_enumeration(iter_items_nodelists, counter_formatter, render_context, *, target_id_generator=None, annotations=None, nested_depth=0)
render_heading(heading_nodelist, render_context, *, heading_level=1, inline_heading=False, target_id=None, annotations=None)
render_verbatim(value, render_context, *, is_block_level=False, annotations=None, target_id=None)

Render a hyperlink as plain text.

The displayed content is always rendered. If display_href_urls is True and the link is not a local anchor, the URL is appended in angle brackets (e.g., display <href>). Local anchor links (starting with #) are never shown in the text output.

Parameters:

  • ref_type – The type of reference (e.g., 'href', 'url', 'ref').

  • href –

    The link target. Can be:

    • an external URL, or

    • an anchor fragment ('#fragment-name') for links within the document. The #fragment-name scheme is used universally, even for non-HTML output formats; it is up to the renderer subclass to translate the linking scheme.

  • display_nodelist – The node list for the displayed link text.

  • render_context – The current render context.

  • annotations – Optional list of annotation strings.

Returns:

The rendered link as a plain-text string.

render_float(float_instance, render_context)
render_graphics_block(graphics_resource, render_context)
render_cells(cells_model, render_context, target_id=None)
class flm.fragmentrenderer.text.FragmentRendererInformation
FragmentRendererClass

alias of TextFragmentRenderer

format_name = 'text'

LaTeX Renderer

class flm.fragmentrenderer.latex.LatexFragmentRenderer(**kwargs)

Fragment renderer that produces LaTeX output.

Renders FLM node trees into standard LaTeX code suitable for compilation with pdflatex, lualatex, or xelatex. Uses pylatexenc.latexencode for Unicode-to-LaTeX escaping and emits \hyperref / \href commands for links.

Delayed render markers use the form \FLMDLYD{delayed_key}.

Important

No stray comments assumption. At no point in rendered content is there a comment without a corresponding newline following it.

supports_delayed_render_markers = True

We use the marker \FLMDLYD{delayed_key} for delayed content, which cannot be confused with the rest of the LaTeX code that can be generated from this code generator.

heading_commands_by_level: Mapping[int | str, str] = {'theorem': 'flmTheoremHeading', 1: 'section', 2: 'subsection', 3: 'subsubsection', 4: 'paragraph', 5: 'subparagraph', 6: 'subsubparagraph'}
text_format_cmds: Mapping[str, str | None] = {'defterm-term': 'flmDisplayTerm', 'term-in-defining-defterm': None, 'textbf': 'textbf', 'textit': 'textit'}
latex_semantic_block_environments: Mapping[str, str] = {'address': 'flmAddress', 'blockquote': 'flmBlockquote', 'definitionlike': 'flmThmDefinitionLike', 'defterm': 'flmDefterm', 'prooflike': 'flmThmProofLike', 'quotation': 'quotation', 'quote': 'quote', 'theoremlike': 'flmThmTheoremLike'}
latex_lines_environments: Mapping[str, str | None] = {'quote': 'quote'}
latex_macro_no_extra_space_after_dot: str = '\\@'
use_phantom_section: bool = True
latex_label_prefix: str = 'x:'
debug_disable_pin_labels: bool = False
use_flm_macro_for_pinning_labels: bool = True
latex_wrap_verbatim_macro: str | None = None
use_endnote_latex_command: str | None = None
use_citation_latex_command: str | None = None
float_placement_policy: TypeFloatPlacementPolicyDict = {'captiononly': {'centering': '', 'environment': 'center', 'environment_options_str': ''}, 'nothing': {'centering': '', 'environment': 'center', 'environment_options_str': ''}, 'numbercaption': {'environment_options_str': '[hbtp]'}, 'numberonly': {'environment_options_str': '[hbtp]'}}
float_use_centering: str = '\\centering{}'
float_caption_join: str = ': '
float_latex_before_caption: str = '\\flmFloatCaption{'
float_latex_after_caption: str = '}'
graphics_raster_magnification: int | float = 1
graphics_vector_magnification: int | float = 1
latexescape(value)

Escape a plain-text string for safe inclusion in LaTeX output.

Delegates to the UnicodeToLatexEncoder instance created during initialization. Characters that are special in LaTeX ($, &, %, etc.) are replaced with their escaped equivalents; unknown Unicode characters are kept as-is.

Parameters:

value – The plain-text string to escape.

Returns:

The LaTeX-safe string.

Return type:

str

wrap_in_text_format_macro(value, text_formats, render_context)

Wrap already-rendered content in LaTeX text-formatting commands.

Iterates over text_formats in reverse order and nests the content inside the corresponding LaTeX command looked up from text_format_cmds. Formats whose mapping value is None are silently skipped.

Parameters:

  • value (str) – Already-rendered LaTeX content to wrap.

  • text_formats – Iterable of format names (e.g. 'textbf', 'textit').

  • render_context – The current render context (unused by the default implementation but available for subclass overrides).

Returns:

The wrapped LaTeX string.

Return type:

str

wrap_in_latex_enumeration_environment(ltx_environment, annotations, items_content, render_context)

Wrap pre-rendered list/lines content in a LaTeX environment.

Produces \begin{<env>}...\end{<env>} with the annotations emitted as a trailing LaTeX comment on the \begin line.

Parameters:

  • ltx_environment (str) – LaTeX environment name (e.g. 'itemize', 'enumerate', 'flmLines').

  • annotations (list) – Descriptive strings written as a comment after \begin{...}.

  • items_content (str) – Already-rendered inner content.

  • render_context – The current render context.

Returns:

The complete LaTeX environment string.

Return type:

str

pin_label_here(target_id, display_latex, insert_phantom_section=True)

Emit LaTeX code that pins a \label at the current point.

The generated label can be referenced with \ref and will display display_latex as the reference text. Optionally prepends a \phantomsection so that hyperref links point to the correct location.

The label key is formed by prepending latex_label_prefix to target_id.

Parameters:

  • target_id (str) – The logical target identifier (without prefix).

  • display_latex (str) – LaTeX code shown when the label is referenced with \ref.

  • insert_phantom_section (bool) – If True (default) and use_phantom_section is also True, a \phantomsection is emitted before the label.

Returns:

The LaTeX string, or '' if label pinning is disabled via debug_disable_pin_labels.

Return type:

str

render_build_paragraph(nodelist, render_context)
render_inline_content(nodelist, render_context)
render_join(content_list, render_context)

Join together a collection of pieces of content that have already been rendered. Usually you’d want to simply join the strings together with no joiner, which is what the default implementation does.

render_join_blocks(content_list, render_context)

Join together a collection of pieces of content that have already been rendered. Each piece is itself a block of content, which can assumed to be at least paragraph-level or even semantic blocks. Usually you’d want to simply join the strings together with no joiner, which is what the default implementation does.

render_value(value, render_context)
render_empty_error_placeholder(debug_str, render_context)
render_nothing(render_context, annotations=None)
render_verbatim(value, render_context, *, is_block_level=False, annotations=None, target_id=None)
render_math_content(delimiters, nodelist, render_context, displaytype, environmentname=None, target_id=None)
render_text_format(text_formats, nodelist, render_context)
render_semantic_span(content, role, render_context, *, annotations=None, target_id=None)
render_semantic_block(content, role, render_context, *, annotations=None, target_id=None)
render_lines(lines_info_list, render_context, *, role=None, annotations=None, target_id=None)

Render a sequence of inline-content lines separated by line breaks. Collect the lines in a single block-level element. Suitable for typesetting a poem, addresses, or other pieces of text with specific line break requirements.

render_enumeration(iter_items_nodelists, counter_formatter, render_context, *, target_id_generator=None, annotations=None, nested_depth=None)

Doc………. … remember, counter_formatter is given a number starting at 1.

Doc……….. … target_id_generator is a callable, takes one argument (item # starting at 1, like counter_formatter), and returns the anchor name to use for the enumeration item (in LaTeX, will be used in label{…})

render_heading(heading_nodelist, render_context, *, heading_level=1, inline_heading=False, target_id=None, annotations=None)
render_annotation_comment(display_nodelist, render_context, is_block_level=False, color_index=0, initials=None)
render_annotation_highlight(display_nodelist, render_context, is_block_level=False, color_index=0, initials=None)
render_delayed_marker(node, delayed_key, render_context)
render_delayed_dummy_placeholder(node, delayed_key, render_context)
replace_delayed_markers_with_final_values(content, delayed_values)
render_float(float_instance, render_context)
render_graphics_block(graphics_resource, render_context)
collect_graphics_resource(graphics_resource, render_context)
cells_max_width_latexdim = '0.96\\linewidth'
cells_render_method = 'fit_width_test'
render_cells(cells_model, render_context, target_id=None, render_cell_nodelist_contents_fn=None)
class flm.fragmentrenderer.latex.FragmentRendererInformation

Discovery descriptor for the LaTeX fragment renderer.

Exposes LatexFragmentRenderer as the renderer class and provides suggested LaTeX preamble definitions via get_style_information().

FragmentRendererClass

alias of LatexFragmentRenderer

static get_style_information(fragment_renderer)

Return a dict with preamble_suggested_defs LaTeX preamble code.

format_name = 'latex'

Markdown Renderer

class flm.fragmentrenderer.markdown.MarkdownFragmentRenderer(config=None)

Fragment renderer that produces Markdown output.

Renders FLM node trees into Markdown syntax. Text formatting is expressed with * / ** markers, headings use # prefixes, and links use [text](url) notation. Special characters are backslash-escaped.

For features not natively supported by Markdown (e.g. tables / cells), the renderer falls back to HTML via HtmlFragmentRenderer.

Target-id anchors can be emitted in several styles controlled by use_target_ids: 'anchor' (HTML <a> tags), 'pandoc', 'github', or None.

Delayed render markers use the form <FLM:DLYD:delayed_key/>.

supports_delayed_render_markers = True

We use the marker <FLM:DLYD:delayed_key/> for delayed content, which cannot be confused with the rest of the HTML code that can be generated from this code generator.

use_target_ids: Literal['anchor', 'pandoc', 'github', 'None'] = 'anchor'

Determine how target_id’s are set (if they are set). One of ‘anchor’ (<a name="TARGET_ID"></a>), ‘pandoc’ ([]{#TARGET_ID}), ‘github’ ([](#TARGET_ID)) or None (don’t set any target ids).

heading_level_formatter: Mapping[str | int, Callable[[str], str]] = {'theorem': <function MarkdownFragmentRenderer.<lambda>>, 1: <function MarkdownFragmentRenderer.<lambda>>, 2: <function MarkdownFragmentRenderer.<lambda>>, 3: <function MarkdownFragmentRenderer.<lambda>>, 4: <function MarkdownFragmentRenderer.<lambda>>, 5: <function MarkdownFragmentRenderer.<lambda>>, 6: <function MarkdownFragmentRenderer.<lambda>>}
render_build_paragraph(nodelist, render_context)
render_inline_content(nodelist, render_context)
render_join(content_list, render_context)

Join together a collection of pieces of content that have already been rendered. Usually you’d want to simply join the strings together with no joiner, which is what the default implementation does.

render_join_blocks(content_list, render_context)

Join together a collection of pieces of content that have already been rendered. Each piece is itself a block of content, which can assumed to be at least paragraph-level or even semantic blocks. Usually you’d want to simply join the strings together with no joiner, which is what the default implementation does.

render_value(value, render_context)
render_empty_error_placeholder(debug_str, render_context)
render_nothing(render_context, annotations=None)
render_verbatim(value, render_context, *, is_block_level=False, annotations=None, target_id=None)
render_math_content(delimiters, nodelist, render_context, displaytype, environmentname=None, target_id=None)
render_text_format(text_formats, nodelist, render_context)
render_semantic_block(content, role, render_context, *, annotations=None, target_id=None)
render_lines(lines_info_list, render_context, *, role=None, annotations=None, target_id=None)
render_enumeration(iter_items_nodelists, counter_formatter, render_context, *, target_id_generator=None, annotations=None, nested_depth=None)

Render an enumeration as a Markdown unordered list.

Each item is prefixed with - and indented according to the current logical indentation state. The formatted counter tag is prepended to the item content since Markdown has limited support for custom list markers.

Parameters:

  • iter_items_nodelists – An iterable of node lists, one per list item.

  • counter_formatter – A callable counter_formatter(n) returning the formatted tag for item number n (1-based). May return a string or a node list.

  • render_context – The current render context.

  • target_id_generator – Optional callable target_id_generator(n) that takes a 1-based item number and returns an anchor name for the enumeration item, or None if no anchor is needed. The anchor is inserted as inline Markdown target-id code.

  • annotations – Optional list of annotation strings (unused in the current implementation).

  • nested_depth – Optional nesting depth (unused in this renderer).

Returns:

The rendered enumeration as a Markdown string.

render_heading(heading_nodelist, render_context, *, heading_level=1, inline_heading=False, target_id=None, annotations=None)
render_delayed_marker(node, delayed_key, render_context)
render_delayed_dummy_placeholder(node, delayed_key, render_context)
replace_delayed_markers_with_final_values(content, delayed_values)
render_float(float_instance, render_context)
render_graphics_block(graphics_resource, render_context)
render_cells(cells_model, render_context, target_id=None)
class flm.fragmentrenderer.markdown.FragmentRendererInformation

Discovery descriptor for the Markdown fragment renderer.

Exposes MarkdownFragmentRenderer as the renderer class.

FragmentRendererClass

alias of MarkdownFragmentRenderer

format_name = 'markdown'