texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/extensions/index/renderer.py

@@ -0,0 +1,183 @@
+"""TeXSmith renderer hooks converting hashtag spans into LaTeX index entries."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+from bs4 import NavigableString, Tag
+
+from texsmith.adapters.handlers._helpers import (
+    coerce_attribute,
+    gather_classes,
+    mark_processed,
+)
+from texsmith.adapters.latex.utils import escape_latex_chars
+from texsmith.core.context import RenderContext
+from texsmith.core.rules import RenderPhase, renders
+
+from .registry import get_registry
+
+
+TEMPLATE_DIR = Path(__file__).resolve().parent / "templates"
+INDEX_TEMPLATE = TEMPLATE_DIR / "index.tex"
+
+
+def _collect_tags(element: Tag) -> list[str]:
+    tags: list[str] = []
+    index = 0
+    while True:
+        key = "data-tag" if index == 0 else f"data-tag{index}"
+        value = coerce_attribute(element.get(key))
+        if not value:
+            break
+        cleaned = str(value).strip()
+        if cleaned:
+            tags.append(cleaned)
+        index += 1
+    return tags
+
+
+def _strip_formatting(text: str) -> str:
+    """Remove markdown formatting from text."""
+    text = re.sub(r"\*\*\*(.*?)\*\*\*|___(.*?)___", r"\1\2", text)
+    text = re.sub(r"\*\*(.*?)\*\*|__(.*?)__", r"\1\2", text)
+    text = re.sub(r"\*(.*?)\*|_(.*?)_", r"\1\2", text)
+    return text
+
+
+def _format_tag(text: str, legacy: bool) -> str:
+    """Convert markdown formatting to LaTeX."""
+    parts = re.split(r"(\*\*\*.*?\*\*\*)", text)
+    processed = []
+    for part in parts:
+        if part.startswith("***") and part.endswith("***"):
+            content = part[3:-3]
+            processed.append(
+                f"\\textbf{{\\textit{{{escape_latex_chars(content, legacy_accents=legacy)}}}}}"
+            )
+        else:
+            subparts = re.split(r"(\*\*.*?\*\*)", part)
+            for subpart in subparts:
+                if subpart.startswith("**") and subpart.endswith("**"):
+                    content = subpart[2:-2]
+                    processed.append(
+                        f"\\textbf{{{escape_latex_chars(content, legacy_accents=legacy)}}}"
+                    )
+                else:
+                    subsubparts = re.split(r"(\*.*?\*)", subpart)
+                    for subsubpart in subsubparts:
+                        if subsubpart.startswith("*") and subsubpart.endswith("*"):
+                            content = subsubpart[1:-1]
+                            processed.append(
+                                f"\\textit{{{escape_latex_chars(content, legacy_accents=legacy)}}}"
+                            )
+                        else:
+                            processed.append(escape_latex_chars(subsubpart, legacy_accents=legacy))
+    return "".join(processed)
+
+
+def _normalise_style(value: str | None) -> str:
+    if not value:
+        return ""
+    cleaned = str(value).strip().lower()
+    if cleaned == "ib":
+        cleaned = "bi"
+    if cleaned in {"b", "i", "bi"}:
+        return cleaned
+    return ""
+
+
+def _apply_style(fragment: str, style: str) -> str:
+    if style == "b":
+        return f"\\textbf{{{fragment}}}"
+    if style == "i":
+        return f"\\textit{{{fragment}}}"
+    if style == "bi":
+        return f"\\textbf{{\\textit{{{fragment}}}}}"
+    return fragment
+
+
+_REGISTER_ATTR = "_texsmith_index_registered"
+
+
+@renders(
+    "span",
+    phase=RenderPhase.INLINE,
+    priority=44,
+    name="texsmith_index",
+    nestable=False,
+    auto_mark=False,
+)
+def render_index(element: Tag, context: RenderContext) -> None:
+    """Convert ``<span class="ts-hashtag">`` elements into LaTeX index commands."""
+    classes = gather_classes(element.get("class"))
+    if "ts-hashtag" not in classes and "ts-index" not in classes:
+        return
+
+    tags = _collect_tags(element)
+    if not tags:
+        return
+
+    registry_name = coerce_attribute(element.get("data-registry"))
+    style_value = _normalise_style(coerce_attribute(element.get("data-style")))
+    legacy = getattr(context.config, "legacy_latex_accents", False)
+
+    formatted_tags = [_format_tag(tag, legacy=legacy) for tag in tags]
+    if style_value and formatted_tags:
+        formatted_tags[-1] = _apply_style(formatted_tags[-1], style_value)
+
+    sort_tags = [_strip_formatting(tag) for tag in tags]
+
+    entries = []
+    for f_tag, s_tag in zip(formatted_tags, sort_tags, strict=True):
+        escaped_s_tag = escape_latex_chars(s_tag, legacy_accents=legacy)
+        if f_tag == escaped_s_tag:
+            entries.append(f_tag)
+        else:
+            entries.append(f"{escaped_s_tag}@{f_tag}")
+
+    entry_str = "!".join(entries)
+
+    visible_text = element.get_text(strip=False) or ""
+
+    latex = context.formatter.index(
+        visible_text,
+        entry=entry_str,
+        style="",
+        styled_entry=None,
+        registry=registry_name,
+    )
+
+    registry = get_registry()
+    registry.add(tuple(sort_tags))
+
+    state = context.state
+    state.has_index_entries = True
+    index_entries = getattr(state, "index_entries", None)
+    if isinstance(index_entries, list):
+        index_entries.append(tuple(sort_tags))
+
+    node = mark_processed(NavigableString(latex))
+    context.mark_processed(element)
+    context.suppress_children(element)
+    element.replace_with(node)
+
+
+def register(renderer: object) -> None:
+    """Register the index renderer on the provided TeXSmith renderer."""
+    register_callable = getattr(renderer, "register", None)
+    if not callable(register_callable):
+        raise TypeError("Renderer does not expose a 'register' method.")
+    if getattr(renderer, _REGISTER_ATTR, False):
+        return
+    register_callable(render_index)
+
+    formatter = getattr(renderer, "formatter", None)
+    override_template = getattr(formatter, "override_template", None)
+    if callable(override_template):
+        override_template("index", INDEX_TEMPLATE)
+    setattr(renderer, _REGISTER_ATTR, True)
+
+
+__all__ = ["register", "render_index"]

texsmith/extensions/index/templates/index.tex

@@ -0,0 +1 @@
+\VAR{text}\index\BLOCK{ if registry }[\VAR{registry}]\BLOCK{ endif }{\BLOCK{ if styled_entry }\VAR{styled_entry}\BLOCK{ elif style == 'b' }\textbf{\VAR{entry}}\BLOCK{ elif style == 'i' }\textit{\VAR{entry}}\BLOCK{ elif style in ('bi', 'ib') }\textbf{\textit{\VAR{entry}}}\BLOCK{ else }\VAR{entry}\BLOCK{ endif }}

texsmith/extensions/latex_raw.py

@@ -0,0 +1,115 @@
+"""Markdown extension adding support for raw LaTeX fence blocks and inline snippets."""
+
+from __future__ import annotations
+
+from html import escape
+import re
+from xml.etree import ElementTree
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.inlinepatterns import InlineProcessor
+from markdown.preprocessors import Preprocessor
+
+
+class _LatexRawPreprocessor(Preprocessor):
+    """Transform custom `/// latex` fences into hidden HTML nodes."""
+
+    _START_RE = re.compile(r"^\s*///\s+latex\s*$")
+    _END_RE = re.compile(r"^\s*///\s*$")
+    _FENCE_RE = re.compile(r"^\s{0,3}(`{3,}|~{3,})(.*)$")
+
+    def run(self, lines: list[str]) -> list[str]:
+        result: list[str] = []
+        index = 0
+        total = len(lines)
+        in_fence = False
+        fence_char: str | None = None
+        fence_len = 0
+
+        while index < total:
+            line = lines[index]
+
+            fence_match = self._FENCE_RE.match(line)
+            if fence_match:
+                fence_token = fence_match.group(1)
+                token_char = fence_token[0]
+                token_len = len(fence_token)
+                if not in_fence:
+                    in_fence = True
+                    fence_char = token_char
+                    fence_len = token_len
+                else:
+                    if token_char == fence_char and token_len >= fence_len:
+                        in_fence = False
+                        fence_char = None
+                        fence_len = 0
+                result.append(line)
+                index += 1
+                continue
+
+            if in_fence:
+                result.append(line)
+                index += 1
+                continue
+
+            if not self._START_RE.match(line):
+                result.append(line)
+                index += 1
+                continue
+
+            start_index = index
+            index += 1
+            contents: list[str] = []
+
+            while index < total and not self._END_RE.match(lines[index]):
+                contents.append(lines[index])
+                index += 1
+
+            if index >= total:
+                # No closing fence; fall back to raw lines
+                result.extend(lines[start_index:])
+                break
+
+            escaped = escape("\n".join(contents), quote=False)
+            result.append(f'<p class="latex-raw" style="display:none;">{escaped}</p>')
+            index += 1  # Skip closing fence
+
+        return result
+
+
+class _LatexInlineProcessor(InlineProcessor):
+    """Inline handler for ``{latex}[payload]`` markers."""
+
+    def handleMatch(  # noqa: N802 - Markdown inline API requires camelCase
+        self,
+        match: re.Match[str],
+        data: str,
+    ) -> tuple[ElementTree.Element | None, int, int]:  # type: ignore[override]
+        del data
+        payload = match.group("payload")
+        if payload is None:
+            return None, match.start(0), match.end(0)
+
+        element = ElementTree.Element("span")
+        element.set("class", "latex-raw")
+        element.set("style", "display:none;")
+        element.text = escape(payload, quote=False)
+        return element, match.start(0), match.end(0)
+
+
+class LatexRawExtension(Extension):
+    """Register the raw LaTeX block preprocessor."""
+
+    def extendMarkdown(self, md: Markdown) -> None:  # type: ignore[override]  # noqa: N802
+        md.preprocessors.register(_LatexRawPreprocessor(md), "texsmith_latex_raw", priority=27)
+        pattern = r"\{latex\}\[(?P<payload>[^\]]+)\]"
+        processor = _LatexInlineProcessor(pattern, md)
+        md.inlinePatterns.register(processor, "texsmith_latex_inline", 181)
+
+
+def makeExtension(**_: object) -> LatexRawExtension:  # pragma: no cover - API hook  # noqa: N802
+    return LatexRawExtension()
+
+
+__all__ = ["LatexRawExtension", "makeExtension"]

texsmith/extensions/latex_text.py

@@ -0,0 +1,117 @@
+"""Markdown extension to stylize the literal ``LaTeX`` token inside paragraphs."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ElementTree
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.treeprocessors import Treeprocessor
+
+
+_TARGET = "LaTeX"
+
+
+class _LatexTextTreeprocessor(Treeprocessor):
+    """Replace plain ``LaTeX`` occurrences with a styled HTML fragment."""
+
+    def run(self, root: ElementTree.Element) -> None:  # type: ignore[override]
+        for paragraph in root.iter("p"):
+            self._process_element(paragraph)
+
+    # -- internals -----------------------------------------------------
+    def _process_element(self, element: ElementTree.Element) -> None:
+        self._replace_text_node(element)
+        for child in list(element):
+            if self._is_code_element(child):
+                if child.tail:
+                    self._replace_tail(element, child)
+                continue
+
+            self._process_element(child)
+            if child.tail:
+                self._replace_tail(element, child)
+
+    def _replace_text_node(self, element: ElementTree.Element) -> None:
+        text = element.text
+        if not text or _TARGET not in text:
+            return
+
+        parts = text.split(_TARGET)
+        element.text = parts[0]
+        for insert_pos, remainder in enumerate(parts[1:]):
+            fragment = self._build_fragment()
+            element.insert(insert_pos, fragment)
+            if remainder:
+                fragment.tail = remainder
+
+    def _replace_tail(self, parent: ElementTree.Element, child: ElementTree.Element) -> None:
+        tail = child.tail
+        if not tail or _TARGET not in tail:
+            return
+
+        parts = tail.split(_TARGET)
+        child.tail = parts[0]
+        base_index = list(parent).index(child) + 1
+        for offset, remainder in enumerate(parts[1:]):
+            fragment = self._build_fragment()
+            parent.insert(base_index + offset, fragment)
+            if remainder:
+                fragment.tail = remainder
+
+    def _is_code_element(self, element: ElementTree.Element) -> bool:
+        tag = element.tag
+        if isinstance(tag, str):
+            tag = tag.lower()
+        return tag in {"code", "pre"}
+
+    def _build_fragment(self) -> ElementTree.Element:
+        outer = ElementTree.Element(
+            "span",
+            {
+                "class": "latex-text",
+                "style": "font-family: 'Times New Roman', serif;",
+            },
+        )
+        outer.text = "L"
+
+        lowered_a = ElementTree.SubElement(
+            outer,
+            "span",
+            {"style": ("position: relative; top: 0.2em; left: -0.05em; font-size: 0.9em;")},
+        )
+        lowered_a.text = "a"
+        lowered_a.tail = "T"
+
+        small_caps_e = ElementTree.SubElement(
+            outer,
+            "span",
+            {
+                "style": "font-variant: small-caps;",
+            },
+        )
+        small_caps_e.text = "e"
+
+        ElementTree.SubElement(
+            outer,
+            "span",
+            {
+                "style": "font-variant: small-caps; letter-spacing: -0.05em;",
+            },
+        ).text = "X"
+
+        return outer
+
+
+class LatexTextExtension(Extension):
+    """Register the ``LaTeX`` paragraph replacement processor."""
+
+    def extendMarkdown(self, md: Markdown) -> None:  # type: ignore[override]  # noqa: N802
+        md.treeprocessors.register(_LatexTextTreeprocessor(md), "texsmith_latex_text", priority=15)
+
+
+def makeExtension(**_: object) -> LatexTextExtension:  # pragma: no cover - API hook  # noqa: N802
+    return LatexTextExtension()
+
+
+__all__ = ["LatexTextExtension", "makeExtension"]

texsmith/extensions/mermaid.py

@@ -0,0 +1,267 @@
+"""Markdown extension that inlines Mermaid diagrams referenced via images."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+import xml.etree.ElementTree as ElementTree
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.treeprocessors import Treeprocessor
+
+from ..adapters.handlers._mermaid import (
+    MERMAID_FILE_SUFFIXES,
+    extract_mermaid_live_diagram,
+    looks_like_mermaid,
+)
+from ..core.exceptions import InvalidNodeError
+
+
+def _collapse_relative_path(src: str) -> str:
+    """Return a relative path with ``..`` segments normalised away."""
+    if not src or src.startswith(("/", "\\")):
+        return src
+
+    segments: list[str] = []
+    for segment in src.split("/"):
+        if not segment or segment == ".":
+            continue
+        if segment == "..":
+            if segments:
+                segments.pop()
+            continue
+        segments.append(segment)
+    return "/".join(segments)
+
+
+class _MermaidImageTreeprocessor(Treeprocessor):
+    """Replace standalone Mermaid image references with code blocks."""
+
+    def __init__(
+        self,
+        md: Markdown,
+        *,
+        extra_base_paths: Sequence[Path] | None = None,
+    ) -> None:
+        super().__init__(md)
+        self._extra_base_paths = [path for path in (extra_base_paths or []) if path]
+
+    def run(self, root: ElementTree.Element) -> ElementTree.Element:  # type: ignore[override]
+        base_path_value = getattr(self.md, "texsmith_mermaid_base_path", None)
+        base_path: Path | None = None
+        if base_path_value:
+            try:
+                base_path = Path(base_path_value).resolve()
+            except OSError:
+                base_path = Path(base_path_value)
+
+        parent_map: dict[ElementTree.Element, ElementTree.Element] = {}
+        for parent in root.iter():
+            for child in list(parent):
+                parent_map[child] = parent
+
+        for paragraph in list(root.iter("p")):
+            image, link_href = self._extract_image(paragraph)
+            if image is None:
+                continue
+
+            diagram_payload = self._load_diagram(image, base_path)
+            if diagram_payload is None:
+                continue
+            diagram, source, trusted = diagram_payload
+
+            caption = (image.get("alt") or image.get("title") or "").strip()
+            body = self._apply_caption(diagram, caption)
+            if not trusted and not looks_like_mermaid(body):
+                continue
+
+            replacement = self._build_mermaid_block(body, link_href, source)
+            wrapper = self._wrap_with_link(replacement, link_href)
+            self._replace_paragraph(parent_map.get(paragraph), paragraph, wrapper)
+
+        return root
+
+    def _extract_image(
+        self, paragraph: ElementTree.Element
+    ) -> tuple[ElementTree.Element | None, str | None]:
+        if any((node.tail or "").strip() for node in paragraph):
+            return None, None
+        paragraph_text = (paragraph.text or "").strip()
+        if paragraph_text:
+            return None, None
+        if len(paragraph) != 1:
+            return None, None
+
+        node = paragraph[0]
+        if node.tag == "img":
+            if (node.tail or "").strip():
+                return None, None
+            return node, None
+
+        if node.tag == "a" and len(node) == 1 and node[0].tag == "img":
+            image = node[0]
+            if (node.text or "").strip() or (image.tail or "").strip():
+                return None, None
+            href = node.get("href")
+            return image, href
+
+        return None, None
+
+    def _load_diagram(
+        self,
+        image: ElementTree.Element,
+        base_path: Path | None,
+    ) -> tuple[str, str, bool] | None:
+        raw_src = image.get("src")
+        if not raw_src:
+            return None
+
+        cleaned = raw_src.replace("\n", "").replace("\r", "").strip()
+        if not cleaned:
+            return None
+
+        source_hint = cleaned
+        simplified = cleaned.split("?", 1)[0].split("#", 1)[0].lower()
+        if simplified.endswith(MERMAID_FILE_SUFFIXES):
+            if cleaned.startswith(("http://", "https://")):
+                return None
+            resolved = self._resolve_path(cleaned, base_path)
+            if resolved is None:
+                return None
+            try:
+                payload = resolved.read_text(encoding="utf-8")
+            except OSError:
+                return None
+            return payload, str(resolved), True
+
+        try:
+            diagram = extract_mermaid_live_diagram(cleaned)
+        except InvalidNodeError:
+            return None
+        if diagram is not None:
+            return diagram, source_hint, False
+
+        return None
+
+    def _resolve_path(self, src: str, base_path: Path | None) -> Path | None:
+        normalised = _collapse_relative_path(src.replace("\\", "/"))
+        candidate = Path(normalised)
+        if candidate.is_absolute():
+            return candidate if candidate.exists() else None
+
+        search_roots: list[Path] = []
+        if base_path is not None:
+            search_roots.append(base_path)
+        for fallback in self._extra_base_paths:
+            if fallback not in search_roots:
+                search_roots.append(fallback)
+
+        for root in search_roots:
+            resolved = (root / normalised).resolve()
+            if resolved.exists():
+                return resolved
+        return None
+
+    def _apply_caption(self, diagram: str, caption: str) -> str:
+        if not caption:
+            return diagram
+
+        meaningful_line = None
+        for line in diagram.splitlines():
+            stripped = line.strip()
+            if not stripped:
+                continue
+            meaningful_line = stripped
+            break
+
+        if meaningful_line and meaningful_line.startswith("%%"):
+            return diagram
+
+        sanitized = caption.strip()
+        if not sanitized:
+            return diagram
+
+        body = diagram.lstrip("\ufeff")
+        return f"%% {sanitized}\n{body}"
+
+    def _build_mermaid_block(
+        self,
+        diagram: str,
+        link_href: str | None,
+        source_hint: str,
+    ) -> ElementTree.Element:
+        pre = ElementTree.Element("pre", {"class": "mermaid"})
+        if link_href:
+            pre.set("data-mermaid-link", link_href)
+        if source_hint:
+            pre.set("data-mermaid-source", source_hint)
+        pre.text = diagram
+        return pre
+
+    def _wrap_with_link(
+        self,
+        node: ElementTree.Element,
+        link_href: str | None,
+    ) -> ElementTree.Element:
+        if not link_href:
+            return node
+
+        anchor = ElementTree.Element("a", {"href": link_href})
+        anchor.append(node)
+        return anchor
+
+    def _replace_paragraph(
+        self,
+        parent: ElementTree.Element | None,
+        paragraph: ElementTree.Element,
+        replacement: ElementTree.Element,
+    ) -> None:
+        replacement.tail = paragraph.tail
+        if parent is None:
+            return
+        for index, child in enumerate(list(parent)):
+            if child is paragraph:
+                parent.insert(index, replacement)
+                parent.remove(paragraph)
+                return
+
+
+class MermaidExtension(Extension):
+    """Register the Mermaid image treeprocessor."""
+
+    def __init__(self, **kwargs: object) -> None:
+        self.config = {
+            "base_paths": [(), "Additional directories searched for Mermaid files."],
+        }
+        super().__init__(**kwargs)
+
+    @staticmethod
+    def _coerce_paths(paths: Iterable[object]) -> list[Path]:
+        resolved: list[Path] = []
+        for entry in paths:
+            if entry is None:
+                continue
+            try:
+                candidate = Path(entry).expanduser()
+            except TypeError:
+                continue
+            try:
+                resolved.append(candidate.resolve())
+            except OSError:
+                resolved.append(candidate)
+        return resolved
+
+    def extendMarkdown(self, md: Markdown) -> None:  # type: ignore[override]  # noqa: N802
+        extra_paths = self._coerce_paths(self.getConfig("base_paths") or ())
+        processor = _MermaidImageTreeprocessor(md, extra_base_paths=extra_paths)
+        md.treeprocessors.register(processor, "texsmith_mermaid_images", priority=15)
+
+
+def makeExtension(  # noqa: N802 - Markdown expects this entry point name
+    **kwargs: object,
+) -> MermaidExtension:  # pragma: no cover - entry point
+    return MermaidExtension(**kwargs)
+
+
+__all__ = ["MermaidExtension", "makeExtension"]