Handlers¶

Handlers convert BeautifulSoup nodes into LATEX fragments. They run inside the core renderer and are grouped by RenderPhase so transformations can hook into the DOM at the right point.

Render phases at a glance¶

Phase	Purpose	Typical consumers
`RenderPhase.PRE`	Normalise HTML before layout-sensitive transforms (unwrap unwanted tags, capture math spans, detect inline code).	`basic.discard_unwanted`, `inline.inline_code`, diagram preprocessors.
`RenderPhase.BLOCK`	Manipulate block-level nodes when structure is stable (convert `<figure>`, extract tabbed content, manage slot boundaries).	`blocks.tabbed_content`, `media.render_mermaid`.
`RenderPhase.INLINE`	Render inline formatting once blocks are resolved.	`inline.inline_emphasis`, `links.links`, `inline.abbreviation`.
`RenderPhase.POST`	Finalisation pass after children are converted; ideal for numbering, bibliography hooks, or asset emission.	`blocks.tables`, `admonitions.render_admonition`, `media.render_images`.

Handlers are regular Python callables decorated with @renders(...). The decorator declares the HTML selectors, phase, and metadata such as priority, nestable, and whether TeXSmith should auto-mark the node as processed.

Example: add a custom inline macro¶

from bs4 import Tag

from texsmith.core.context import RenderContext
from texsmith.core.rules import RenderPhase, renders


@renders("span", phase=RenderPhase.INLINE, priority=10, name="callout_chips")
def render_callout_chips(element: Tag, context: RenderContext) -> None:
    if "data-callout" not in element.attrs:
        return
    label = element.get_text(strip=True)
    latex = r"\CalloutChip{%s}" % context.escape(label)
    context.write(latex)
    context.mark_processed(element)

Drop the module anywhere on PYTHONPATH and import it before calling texsmith.render. For MkDocs sites, add the import inside a mkdocs plugin or docs/hooks/mkdocs_hooks.py. For programmatic runs, import the module ahead of convert_documents so the decorator executes at import time.

Tip

Handlers should call context.mark_processed(element) when they fully consume a node. Leave the node untouched to let lower-priority handlers run.

Reference¶

Built-in handler collections.

Internal helpers shared across handler modules.

coerce_attribute ¶

coerce_attribute(value: Any) -> str | None

Normalise a BeautifulSoup attribute value to a string when possible.

Source code in src/texsmith/adapters/handlers/_helpers.py

def coerce_attribute(value: Any) -> str | None:
    """Normalise a BeautifulSoup attribute value to a string when possible."""
    if isinstance(value, str):
        return value
    if isinstance(value, bytes):
        try:
            return value.decode("utf-8")
        except UnicodeDecodeError:
            return None
    if isinstance(value, Iterable):
        for item in value:
            if isinstance(item, str):
                return item
    return None

gather_classes ¶

gather_classes(value: Any) -> list[str]

Return a list of classes extracted from a BeautifulSoup attribute.

Source code in src/texsmith/adapters/handlers/_helpers.py

def gather_classes(value: Any) -> list[str]:
    """Return a list of classes extracted from a BeautifulSoup attribute."""
    if isinstance(value, str):
        return [value]
    if isinstance(value, Iterable) and not isinstance(value, (bytes, bytearray)):
        return [cast(str, item) for item in value if isinstance(item, str)]
    return []

is_valid_url ¶

is_valid_url(url: str) -> bool

Check whether a URL string has a valid scheme/netloc combination.

Source code in src/texsmith/adapters/handlers/_helpers.py

def is_valid_url(url: str) -> bool:
    """Check whether a URL string has a valid scheme/netloc combination."""
    try:
        result = urlparse(url)
    except ValueError:
        return False
    return bool(result.scheme and result.netloc)

mark_processed ¶

mark_processed(node: NodeT) -> NodeT

Mark a BeautifulSoup node as processed and return it for chaining.

Source code in src/texsmith/adapters/handlers/_helpers.py

def mark_processed(node: NodeT) -> NodeT:
    """Mark a BeautifulSoup node as processed and return it for chaining."""
    cast(Any, node).processed = True  # type: ignore[attr-defined]
    return node

resolve_asset_path ¶

resolve_asset_path(
    file_path: Path, path: str | Path
) -> Path | None

Resolve an asset path relative to a Markdown source file.

Source code in src/texsmith/adapters/handlers/_helpers.py

def resolve_asset_path(file_path: Path, path: str | Path) -> Path | None:
    """Resolve an asset path relative to a Markdown source file."""
    origin = Path(file_path)
    if origin.name == "index.md":
        origin = origin.parent
    target = (origin / path).resolve()
    return target if target.exists() else None

Handlers for generic admonition and callout markup.

render_blockquote_callouts ¶

render_blockquote_callouts(
    element: Tag, context: RenderContext
) -> None

Handle Obsidian/Docusaurus style blockquote callouts.

Source code in src/texsmith/adapters/handlers/admonitions.py

@renders(
    "blockquote",
    phase=RenderPhase.POST,
    priority=15,
    name="blockquote_callouts",
    nestable=True,
    auto_mark=False,
)
def render_blockquote_callouts(element: Tag, context: RenderContext) -> None:
    """Handle Obsidian/Docusaurus style blockquote callouts."""
    first_paragraph = element.find("p")
    if first_paragraph is None:
        return

    first_text_node = next(
        (child for child in first_paragraph.contents if isinstance(child, NavigableString)),
        None,
    )
    if first_text_node is None:
        return

    raw_text = str(first_text_node)
    stripped = raw_text.lstrip()
    offset = len(raw_text) - len(stripped)
    match = CALLOUT_PATTERN.match(stripped)
    if not match:
        return

    callout_type = match.group("kind").lower()
    remainder = match.group("content") or ""
    remainder = remainder.lstrip()

    first_text_node.replace_with(NavigableString(raw_text[:offset] + remainder))

    lines_with_endings = remainder.splitlines(keepends=True)
    lines = [line.strip() for line in remainder.splitlines() if line.strip()]
    title = lines[0] if lines else callout_type.capitalize()

    if len(lines_with_endings) > 1:
        prefix_length = len(raw_text[:offset]) + len(lines_with_endings[0])
        _trim_paragraph_prefix(first_paragraph, prefix_length)
        first_text = next(
            (child for child in first_paragraph.contents if isinstance(child, NavigableString)),
            None,
        )
        if first_text is not None:
            first_text.replace_with(NavigableString(str(first_text).lstrip()))
    else:
        first_paragraph.decompose()

    classes = gather_classes(element.get("class"))
    preserved = [cls for cls in classes if cls != "admonition"]
    new_classes = ["admonition", callout_type]
    for cls in preserved:
        if cls not in new_classes:
            new_classes.append(cls)
    element["class"] = new_classes
    _promote_callout(element, context, classes=new_classes, title=title)

render_details_admonitions ¶

render_details_admonitions(
    element: Tag, context: RenderContext
) -> None

Handle collapsible callouts converted from MkDocs Material's details blocks.

Source code in src/texsmith/adapters/handlers/admonitions.py

@renders(
    "details",
    phase=RenderPhase.POST,
    priority=55,
    name="details_admonitions",
    nestable=True,
    auto_mark=False,
)
def render_details_admonitions(element: Tag, context: RenderContext) -> None:
    """Handle collapsible callouts converted from MkDocs Material's details blocks."""
    classes = gather_classes(element.get("class"))
    if "exercise" in classes:
        return

    title = ""
    if summary := element.find("summary"):
        title = summary.get_text(strip=True)
        summary.decompose()

    _promote_callout(element, context, classes=classes, title=title or "")

render_div_admonitions ¶

render_div_admonitions(
    element: Tag, context: RenderContext
) -> None

Handle MkDocs Material admonition blocks.

Source code in src/texsmith/adapters/handlers/admonitions.py

@renders(
    "div",
    phase=RenderPhase.POST,
    priority=50,
    name="admonitions",
    nestable=True,
    auto_mark=False,
)
def render_div_admonitions(element: Tag, context: RenderContext) -> None:
    """Handle MkDocs Material admonition blocks."""
    classes = gather_classes(element.get("class"))
    if "admonition" not in classes:
        return
    if "exercise" in classes:
        return

    title = _extract_title(element.find("p", class_="admonition-title"))
    _promote_callout(element, context, classes=classes, title=title)

render_texsmith_callouts ¶

render_texsmith_callouts(
    element: Tag, context: RenderContext
) -> None

Convert promoted callout nodes once their children have rendered.

Source code in src/texsmith/adapters/handlers/admonitions.py

@renders(
    "texsmith-callout",
    phase=RenderPhase.POST,
    priority=140,
    name="finalize_callouts",
    nestable=False,
    auto_mark=False,
    after_children=True,
)
def render_texsmith_callouts(element: Tag, context: RenderContext) -> None:
    """Convert promoted callout nodes once their children have rendered."""
    classes = gather_classes(element.get("class"))
    title = element.attrs.pop("data-callout-title", "")
    _render_admonition(element, context, classes=classes, title=title)

Built-in baseline handlers used by the renderer.