Skip to content

Text

Templates

rn_forge.commons.text.templates renders Jinja templates. It needs the templates extra and is imported directly, never through rn_forge.commons.

uv add "rn-forge-commons[templates]"

TemplateEngine.cached returns one shared engine per set of arguments, so each template compiles once per process. Do not mutate its environment.

from rn_forge.commons.text.templates import TemplateEngine

engine = TemplateEngine.cached(package="my_tool", package_path="templates")

engine.render("pyproject.toml.j2", {"name": "demo"})
engine.render_string("Hello {{ name }}", {"name": "world"})

Undefined variables raise RenderError. Pass strict=False to render them empty.

For HTML output, pass autoescape=True so every rendered value is escaped:

html = TemplateEngine.cached(package="my_tool", autoescape=True)
html.render_string("{{ v }}", {"v": "<b>"})  # "&lt;b&gt;"

The to_toml and to_yaml filters serialize a mapping:

engine.render_string("{{ data | to_toml }}", {"data": {"a": 1}})

Other keyword arguments reach jinja2.Environment. To render YAML that uses {{ }} itself, move the variable delimiters:

engine = TemplateEngine.cached(
    directory="templates",
    variable_start_string="[[",
    variable_end_string="]]",
)

Markdown

rn_forge.commons.text.markdown reads the structure of a Markdown document. It needs the markdown extra and is imported directly, never through rn_forge.commons.

uv add "rn-forge-commons[markdown]"

Anchors follow Python-Markdown's toc extension, which MkDocs uses. Links and tables come from a CommonMark parser, so a link inside code is not a link.

Parsing is shared automatically: the headings, anchors, title, links, tables and fenced-code helpers reuse one parsed structure per document, so no caller-side cache is needed. The reuse is process-local and keyed by the full text, so changed text is parsed afresh and equal text from any source shares an entry. At most 2048 documents are retained, counted in entries rather than bytes; a document evicted since its last use is parsed again. Every call returns a fresh list or set that the caller may modify.

from rn_forge.commons.text.markdown import MarkdownUtils

page = """# Guide

See [setup](setup.md#install) and [the site](https://example.com).

| Name | Role |
| -- | -- |
| ann | dev |
"""

MarkdownUtils.anchors(page)  # {"guide"}
[link for link in MarkdownUtils.links(page) if not MarkdownUtils.is_external(link)]
# ["setup.md#install"]
MarkdownUtils.tables(page)[0].rows  # (("ann", "dev"),)