simplex-web 0.2.0__py3-none-any.whl

simplex/web/bibtex.py

@@ -0,0 +1,129 @@
+"""Minimal pure-Python BibTeX parser.
+
+A `.bib` file is a sequence of `@type{key, field = value, ...}` entries.
+This module turns one such file into a sequence of
+``(key, entry_type, fields)`` triples; `bibliography.py` consumes those
+and assembles `BibEntry` / `Bibliography` models on top.
+
+Why pure-Python (not `bibtexparser`):
+
+- We need a tiny, predictable subset: brace- or quote-delimited field values,
+  comma-separated fields, the `@string` / `@preamble` / `@comment` skip set.
+- Hand-rolling that takes <120 LOC; we don't pull in another dep for it.
+
+Open issues we deliberately don't handle (and don't need for deck notes):
+
+- `@string{x = "y"}` substitution -- treats string aliases as opaque tokens.
+- Concatenation with `#` -- left as-is; doesn't appear in our refs.bib files.
+"""
+
+import re
+from collections.abc import Iterator
+
+_ENTRY_HEAD = re.compile(r"@(?P<type>\w+)\s*\{\s*(?P<key>[^,\s]+)\s*,", re.IGNORECASE)
+_SKIP_TYPES = {"string", "preamble", "comment"}
+
+
+def parse(text: str) -> Iterator[tuple[str, str, dict[str, str]]]:
+    """Yield `(key, entry_type, fields)` triples from a `.bib` document."""
+    cleaned = "\n".join(line for line in text.splitlines() if not line.lstrip().startswith("%"))
+    pos = 0
+    while pos < len(cleaned):
+        match = _ENTRY_HEAD.search(cleaned, pos)
+        if not match:
+            return
+        entry_type = match.group("type")
+        if entry_type.lower() in _SKIP_TYPES:
+            pos = _skip_balanced(cleaned, match.end() - 1)
+            continue
+        body_end = _find_close_brace(cleaned, match.end())
+        if body_end < 0:
+            return
+        yield match.group("key"), entry_type, _parse_fields(cleaned[match.end() : body_end])
+        pos = body_end + 1
+
+
+def _find_close_brace(text: str, start: int) -> int:
+    """Return the index of the matching `}` starting from `start` (depth 1),
+    or -1 if unterminated. Skips over `"..."` quoted spans (BibTeX has no
+    backslash escapes inside quotes)."""
+    depth = 1
+    i = start
+    while i < len(text):
+        ch = text[i]
+        if ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                return i
+        elif ch == '"':
+            i = text.find('"', i + 1)
+            if i < 0:
+                return -1
+        i += 1
+    return -1
+
+
+def _skip_balanced(text: str, brace_pos: int) -> int:
+    """Return the index *after* a `{...}` group that starts at `brace_pos`."""
+    end = _find_close_brace(text, brace_pos + 1)
+    return end + 1 if end >= 0 else len(text)
+
+
+def _parse_fields(body: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    i = 0
+    while i < len(body):
+        while i < len(body) and body[i] in " \t\r\n,":
+            i += 1
+        if i >= len(body):
+            break
+        name_start = i
+        while i < len(body) and body[i] not in "= \t\r\n":
+            i += 1
+        name = body[name_start:i].lower()
+        if not name:
+            break
+        while i < len(body) and body[i] != "=":
+            i += 1
+        i += 1
+        while i < len(body) and body[i] in " \t\r\n":
+            i += 1
+        if i >= len(body):
+            break
+        value, i = _read_value(body, i)
+        fields[name] = value
+    return fields
+
+
+def _read_value(text: str, start: int) -> tuple[str, int]:
+    """Read one field value (braced, quoted, or bare token). Returns the
+    value plus the index of the next unread character."""
+    if text[start] == "{":
+        end = _find_close_brace(text, start + 1)
+        if end < 0:
+            return text[start + 1 :].strip(), len(text)
+        return _normalise_ws(text[start + 1 : end]), end + 1
+    if text[start] == '"':
+        end = text.find('"', start + 1)
+        if end < 0:
+            return text[start + 1 :].strip(), len(text)
+        return _normalise_ws(text[start + 1 : end]), end + 1
+    j = start
+    while j < len(text) and text[j] not in ",\n}":
+        j += 1
+    return text[start:j].strip(), j
+
+
+def _normalise_ws(s: str) -> str:
+    return re.sub(r"\s+", " ", s).strip()
+
+
+def unbrace(s: str) -> str:
+    """Drop the outer `{...}` braces BibTeX uses to protect title casing.
+
+    Public because `bibliography.py` calls it when rendering field values
+    (titles, journals) without dragging in regex internals.
+    """
+    return re.sub(r"[{}]", "", s)

simplex/web/builder.py

@@ -0,0 +1,321 @@
+"""Build the full static portal under ``site/``.
+
+Pipeline (per deck):
+
+1. ``render.runner.render`` (subprocess, skipped when ``render=False``).
+2. ``render.pdf.export`` (best-effort).
+3. ``render.reconcile.build_manifest`` reads native section JSON +
+   manim-slides PresentationConfig -> main/sub tree.
+4. ``render.thumbnail.generate`` per main slide (default rule: second-to-last
+   subsection's last frame).
+5. ``render.html.render_html`` renders our custom RevealJS template with
+   the reconciled tree + palette CSS.
+6. ``web.notes.render`` runs ``notes.md`` through markdown-it.
+7. Write ``index.html`` for the deck page.
+
+No render cache. Manim's per-animation cache + ``save_sections=True``
+(applied by the plugin) gives slide-level incrementality for free.
+"""
+
+import contextlib
+import shutil
+import subprocess
+from datetime import UTC, datetime, time
+from pathlib import Path
+from typing import Any, cast
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from simplex.deck.config import DeckConfig
+from simplex.deck.registry import Section, SectionedRegistry, discover
+from simplex.deck.section import SectionConfig
+from simplex.render import html, pdf, reconcile, runner, thumbnail
+from simplex.theme.web_css import render_web_css
+from simplex.web import notes, vendor
+from simplex.web.bibliography import Bibliography
+from simplex.web.site_config import SiteConfig
+
+
+def _jinja(site_cfg: SiteConfig) -> Environment:
+    env = Environment(
+        loader=PackageLoader("simplex.web", "templates"),
+        autoescape=select_autoescape(["html", "j2"]),
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+    def static(path: str) -> str:
+        return site_cfg.url("static/" + path.lstrip("/"))
+
+    globals_: dict[str, Any] = cast(dict[str, Any], env.globals)
+    globals_["static"] = static
+    globals_["site"] = site_cfg
+    return env
+
+
+def _copy_static(site_dir: Path) -> None:
+    """Copy bundled static assets into ``site/static/``."""
+    src = Path(__file__).parent / "static"
+    src.mkdir(parents=True, exist_ok=True)
+    vendor.ensure(src)
+    dst = site_dir / "static"
+    dst.mkdir(parents=True, exist_ok=True)
+    for entry in src.iterdir():
+        if entry.name in {"README.md", ".gitkeep"}:
+            continue
+        target = dst / entry.name
+        if entry.is_dir():
+            shutil.copytree(entry, target, dirs_exist_ok=True)
+        else:
+            shutil.copy2(entry, target)
+
+
+def _maybe_render(
+    deck: DeckConfig,
+    media_dir: Path,
+    *,
+    render: bool,
+    scenes: tuple[str, ...] = (),
+    write_last_frame: bool = False,
+) -> None:
+    if not render:
+        return
+    deck_scenes = tuple(s for s in scenes if s in deck.scene_class_names)
+    if scenes and not deck_scenes:
+        return
+    runner.render(deck, output_dir=media_dir, scenes=deck_scenes, write_last_frame=write_last_frame)
+    with contextlib.suppress(subprocess.SubprocessError, FileNotFoundError, ImportError):
+        pdf.export(deck, output_dir=media_dir)
+
+
+def _has_pdf(deck: DeckConfig, deck_dir: Path) -> bool:
+    return (deck_dir / f"{deck.slug}.pdf").exists()
+
+
+def _has_notes_pdf(deck_dir: Path) -> bool:
+    return (deck_dir / "notes.pdf").exists()
+
+
+def _load_bibliography(deck_path: Path) -> Bibliography | None:
+    refs = deck_path / "refs.bib"
+    return Bibliography.load(refs) if refs.exists() else None
+
+
+def _site_thumb(deck_out: Path, thumbs: dict[int, Path]) -> str | None:
+    """Return the cover thumbnail (main slide #1) for a deck card."""
+    first = thumbs.get(1)
+    if first is None:
+        return None
+    if first.is_absolute():
+        try:
+            first = first.relative_to(deck_out)
+        except ValueError:
+            return None
+    return first.as_posix()
+
+
+def _deck_created_timestamp(deck: DeckConfig) -> float:
+    """Sort key for "latest" decks: explicit creation date, then file mtime."""
+    if deck.created_at is not None:
+        return datetime.combine(deck.created_at, time.min, tzinfo=UTC).timestamp()
+    toml = deck.path / "deck.toml"
+    with contextlib.suppress(OSError):
+        return toml.stat().st_mtime
+    return 0.0
+
+
+def _deck_created_label(deck: DeckConfig) -> str:
+    if deck.created_at is not None:
+        return deck.created_at.strftime("%b %d, %Y")
+    toml = deck.path / "deck.toml"
+    with contextlib.suppress(OSError):
+        return datetime.fromtimestamp(toml.stat().st_mtime, UTC).strftime("%b %d, %Y")
+    return ""
+
+
+def _latest_section(registry: SectionedRegistry, *, limit: int = 12) -> Section | None:
+    decks = sorted(registry.all_decks, key=_deck_created_timestamp, reverse=True)
+    if not decks:
+        return None
+    return Section(
+        config=SectionConfig(
+            slug="latest",
+            title="Latest decks",
+            blurb="Newest work first.",
+            order=-1,
+        ),
+        decks=tuple(decks[:limit]),
+    )
+
+
+def _build_deck(
+    deck: DeckConfig,
+    *,
+    site_dir: Path,
+    site_cfg: SiteConfig,
+    env: Environment,
+    render: bool,
+    scenes: tuple[str, ...] = (),
+    watch: bool = False,
+) -> tuple[str | None, str | None]:
+    """Render one deck. Returns ``(cover thumbnail, carousel gif)`` hrefs."""
+    deck_out = site_dir / "decks" / deck.slug
+    deck_out.mkdir(parents=True, exist_ok=True)
+
+    _maybe_render(deck, deck_out, render=render, scenes=scenes)
+
+    manifest = reconcile.build_manifest(deck, media_dir=deck_out)
+    thumbs = thumbnail.generate(deck, manifest, site_deck_dir=deck_out, cache_dir=deck_out)
+    preview_gif = thumbnail.generate_carousel_gif(
+        deck,
+        manifest,
+        site_deck_dir=deck_out,
+        cache_dir=deck_out,
+    )
+
+    enriched = tuple(
+        main.model_copy(update={"thumbnail": thumbs.get(main.index)})
+        for main in manifest.main_slides
+    )
+
+    html.render_html(
+        deck,
+        manifest.model_copy(update={"main_slides": enriched}),
+        output_dir=deck_out,
+        static_prefix=site_cfg.url("static"),
+        watch=watch,
+    )
+
+    notes_md = deck.path / "notes.md"
+    notes_html = ""
+    if notes_md.exists():
+        bib = _load_bibliography(deck.path)
+        notes_html = notes.render(notes_md, slide_count=len(enriched), bibliography=bib)
+
+    total_seconds = sum(m.duration_s for m in enriched)
+    total_minutes: int | None = int(total_seconds // 60) if total_seconds > 0 else None
+    if deck.duration_minutes is not None:
+        total_minutes = deck.duration_minutes
+
+    page = env.get_template("deck.html").render(
+        deck=deck,
+        slides=enriched,
+        slide_count=len(enriched),
+        total_duration_min=total_minutes,
+        has_pdf=_has_pdf(deck, deck_out),
+        has_notes_pdf=_has_notes_pdf(deck_out),
+        notes_html=notes_html,
+        palette_css=render_web_css(deck.resolved_web_palette()),
+    )
+    (deck_out / "index.html").write_text(page, encoding="utf-8")
+    return (
+        _site_thumb(deck_out, thumbs),
+        preview_gif.as_posix() if preview_gif is not None else None,
+    )
+
+
+def _build_section_page(
+    section: Section,
+    site_dir: Path,
+    env: Environment,
+    thumbs: dict[str, str | None],
+    preview_gifs: dict[str, str | None],
+    deck_dates: dict[str, str],
+    palette_css: str,
+) -> None:
+    out = site_dir / "sections" / section.config.slug
+    out.mkdir(parents=True, exist_ok=True)
+    page = env.get_template("section.html").render(
+        section=section,
+        thumbs=thumbs,
+        preview_gifs=preview_gifs,
+        deck_dates=deck_dates,
+        palette_css=palette_css,
+    )
+    (out / "index.html").write_text(page, encoding="utf-8")
+
+
+def _build_index(
+    registry: SectionedRegistry,
+    site_dir: Path,
+    env: Environment,
+    thumbs: dict[str, str | None],
+    preview_gifs: dict[str, str | None],
+    deck_dates: dict[str, str],
+    palette_css: str,
+) -> None:
+    page = env.get_template("index.html").render(
+        registry=registry,
+        latest_section=_latest_section(registry),
+        thumbs=thumbs,
+        preview_gifs=preview_gifs,
+        deck_dates=deck_dates,
+        palette_css=palette_css,
+    )
+    (site_dir / "index.html").write_text(page, encoding="utf-8")
+
+
+def _site_palette_css(site_cfg: SiteConfig) -> str:
+    """Return CSS for the site-wide palette (uses site_cfg.theme if set, else default)."""
+    from simplex.theme.presets import get as get_theme
+
+    theme_name = getattr(site_cfg, "theme", None) or "dastimator_dark"
+    return render_web_css(get_theme(theme_name).web_palette)
+
+
+def build(
+    decks_dir: Path,
+    site_dir: Path,
+    *,
+    render: bool = True,
+    site_cfg: SiteConfig | None = None,
+    only: tuple[str, ...] = (),
+    scenes: tuple[str, ...] = (),
+    watch: bool = False,
+) -> None:
+    """Discover decks, render them, write the static site."""
+    site_cfg = site_cfg or SiteConfig.load(repo_root=decks_dir.parent)
+    registry = discover(decks_dir, default_section_order=site_cfg.default_section_order)
+    site_dir.mkdir(parents=True, exist_ok=True)
+    env = _jinja(site_cfg)
+    _copy_static(site_dir)
+
+    only_set = set(only)
+    deck_thumbs: dict[str, str | None] = {}
+    deck_preview_gifs: dict[str, str | None] = {}
+    deck_dates = {deck.slug: _deck_created_label(deck) for deck in registry.all_decks}
+    for section in registry.sections:
+        for deck in section.decks:
+            if only_set and deck.slug not in only_set:
+                continue
+            deck_thumbs[deck.slug], deck_preview_gifs[deck.slug] = _build_deck(
+                deck,
+                site_dir=site_dir,
+                site_cfg=site_cfg,
+                env=env,
+                render=render,
+                scenes=scenes,
+                watch=watch,
+            )
+
+    site_palette_css = _site_palette_css(site_cfg)
+    for section in registry.sections:
+        _build_section_page(
+            section,
+            site_dir,
+            env,
+            deck_thumbs,
+            deck_preview_gifs,
+            deck_dates,
+            site_palette_css,
+        )
+
+    _build_index(
+        registry,
+        site_dir,
+        env,
+        deck_thumbs,
+        deck_preview_gifs,
+        deck_dates,
+        site_palette_css,
+    )

simplex/web/callouts.py

@@ -0,0 +1,134 @@
+r"""Theorem-environment callouts + ``\ref{}`` resolution.
+
+Rewrites ``<blockquote><p><strong>Theorem 3.1.</strong>...</p></blockquote>``
+shapes into colour-coded, anchorable ``<aside>`` blocks:
+
+    <aside class="callout callout-theorem" id="theorem-3-1">
+      <span class="callout-tag">Theorem 3.1.</span> Let f...
+    </aside>
+
+Recognised types (case-insensitive): **theorem, lemma, proposition,
+corollary, claim, fact, definition, example, remark, proof, observation,
+note**. Anything else stays a normal blockquote.
+
+Also resolves the placeholders emitted by `web/refs.py`:
+
+    <a class="ref" data-simplex-ref="theorem-3-1" href="#theorem-3-1">
+      theorem-3-1
+    </a>
+        |
+        v
+    <a class="ref" href="#theorem-3-1">Theorem 3.1</a>
+
+Unknown ref ids get the ``ref-stale`` class (same convention as
+``cite-stale`` / ``slide-ref-stale``).
+
+Pure HTML transformation -- the markdown-it pipeline stays untouched.
+"""
+
+import re
+from collections import defaultdict
+
+# Types we colour-code. Order matters only for matching priority -- longer
+# names first so "Proposition" beats a hypothetical "Prop" prefix.
+_TYPES: tuple[str, ...] = (
+    "Proposition",
+    "Definition",
+    "Observation",
+    "Corollary",
+    "Theorem",
+    "Example",
+    "Lemma",
+    "Remark",
+    "Proof",
+    "Claim",
+    "Fact",
+    "Note",
+)
+_TYPES_LC: frozenset[str] = frozenset(t.lower() for t in _TYPES)
+_TYPE_ALT = "|".join(_TYPES)
+
+# Match a leading `<p><strong>Theorem 3.1.</strong>` inside a blockquote.
+# The number is optional (``Proof.`` / ``Remark.`` may stand alone). We
+# capture the trailing period(s) too so the tag prints faithfully.
+_TAG_RE = re.compile(
+    rf"<p>\s*<strong>\s*(?P<type>{_TYPE_ALT})"
+    r"(?:\s+(?P<num>\d+(?:\.\d+)*))?\s*\.\s*</strong>\s*",
+    re.IGNORECASE,
+)
+_BLOCKQUOTE_RE = re.compile(r"<blockquote>(?P<body>.*?)</blockquote>", re.DOTALL)
+_REF_RE = re.compile(
+    r'<a class="ref" data-simplex-ref="(?P<id>[^"]+)" '
+    r'href="#(?P=id)">(?P<fallback>[^<]+)</a>'
+)
+
+
+def transform(html: str, *, extra_labels: dict[str, str] | None = None) -> str:
+    """Rewrite theorem-style blockquotes and resolve `\\ref{}` placeholders.
+
+    `extra_labels` lets other passes (e.g. `equations.transform`) seed the
+    label map: any id present there is reachable via `\\ref{id}` and
+    rendered with the supplied display string. Callout ids overwrite
+    extra labels of the same name (rare, but the callout is the more
+    specific definition).
+
+    Two-pass:
+      1. Walk every blockquote, detect callout type, rewrite to `<aside>`,
+         and record the label map (`"theorem-3-1" -> "Theorem 3.1"`).
+      2. Walk every `<a class="ref">` placeholder and substitute the
+         display label, combining `extra_labels` with the callout map.
+    """
+    labels: dict[str, str] = dict(extra_labels or {})
+    # Auto-numbering for unnumbered callouts of the same type (e.g. multiple
+    # standalone "Proof." blocks). Keyed by lowercase type.
+    counters: dict[str, int] = defaultdict(int)
+
+    def rewrite_blockquote(match: re.Match[str]) -> str:
+        body = match.group("body")
+        tag_match = _TAG_RE.search(body)
+        if not tag_match:
+            return match.group(0)
+        # Bail out if the tag isn't actually at the top of the blockquote --
+        # we don't want to rewrite a quoted theorem reference appearing
+        # mid-paragraph as a callout.
+        prefix = body[: tag_match.start()].strip()
+        if prefix:
+            return match.group(0)
+
+        kind = tag_match.group("type").lower()
+        if kind not in _TYPES_LC:
+            return match.group(0)
+
+        num = tag_match.group("num")
+        if num:
+            slug_num = num.replace(".", "-")
+            display = f"{tag_match.group('type').title()} {num}"
+        else:
+            counters[kind] += 1
+            slug_num = str(counters[kind])
+            display = tag_match.group("type").title()
+
+        block_id = f"{kind}-{slug_num}"
+        # Record both the bare id and the numbered display so refs work.
+        labels[block_id] = display
+
+        tag_html = f'<span class="callout-tag">{display}.</span> '
+        new_body = body[: tag_match.start()] + "<p>" + tag_html + body[tag_match.end() :]
+        return (
+            f'<aside class="callout callout-{kind}" id="{block_id}" role="note">{new_body}</aside>'
+        )
+
+    out = _BLOCKQUOTE_RE.sub(rewrite_blockquote, html)
+
+    def resolve_ref(match: re.Match[str]) -> str:
+        ref_id = match.group("id")
+        if ref_id in labels:
+            return f'<a class="ref" href="#{ref_id}">{labels[ref_id]}</a>'
+        # Slide refs / external IDs may legitimately not be in the label
+        # map; mark unresolved ones as stale so the build flags them.
+        return (
+            f'<a class="ref ref-stale" href="#{ref_id}" '
+            f'title="Unresolved reference: {ref_id}">{match.group("fallback")}?</a>'
+        )
+
+    return _REF_RE.sub(resolve_ref, out)

simplex/web/citations.py

@@ -0,0 +1,118 @@
+r"""markdown-it-py plugin -- `\cite{key1, key2}` -> linked alpha tag.
+
+Renders as `<a class="cite" href="#bib-{key}">[Auth23]</a>`. Multiple keys
+inside one `\cite{...}` produce a single bracket with separators:
+`[Auth23, Smit24]`.
+
+The plugin stashes the cited keys onto ``state.env["citations"]`` so the
+notes renderer can emit a per-deck bibliography in citation order.
+
+Unknown keys render with the extra class ``cite-stale`` (mirrors
+`slide_ref`) -- the build still produces a usable page that visibly
+flags the issue.
+"""
+
+import re
+from typing import Any
+
+from markdown_it import MarkdownIt
+from markdown_it.rules_inline import StateInline
+
+from simplex.web.bibliography import Bibliography
+
+NAME = "cite"
+ENV_KEY = "citations"
+
+# `\cite{key1, key2}` -- whitespace permitted inside the braces.
+_PATTERN = re.compile(r"\\cite\{([^}]+)\}")
+# BibTeX keys are alphanumerics plus a small punctuation set.
+_KEY_RE = re.compile(r"^[A-Za-z0-9_:\-./+]+$")
+
+
+def make_plugin(bibliography: Bibliography | None) -> Any:
+    """Return a markdown-it plugin bound to the deck's bibliography."""
+
+    bib = bibliography or Bibliography.empty()
+
+    def plugin(md: MarkdownIt) -> None:
+        def rule(state: StateInline, silent: bool) -> bool:
+            if state.src[state.pos] != "\\":
+                return False
+            match = _PATTERN.match(state.src, state.pos)
+            if not match:
+                return False
+            keys = tuple(_clean_keys(match.group(1)))
+            if not keys:
+                return False
+            # Silent / validation mode: callers like `parseLinkLabel` need
+            # `state.pos` advanced past the match, otherwise they loop.
+            if silent:
+                state.pos = match.end()
+                return True
+            _record_keys(state, keys)
+            token = state.push("html_inline", "", 0)
+            token.content = _render(keys, bib)
+            state.pos = match.end()
+            return True
+
+        # Must run before `escape`: markdown-it's escape rule consumes the
+        # leading backslash unconditionally, so `\cite{...}` never reaches
+        # `link`-level rules. Putting `cite` ahead of `escape` keeps the
+        # backslash available to match the LaTeX-style pattern.
+        md.inline.ruler.before("escape", NAME, rule)
+
+    return plugin
+
+
+def _clean_keys(raw: str) -> list[str]:
+    out: list[str] = []
+    for piece in raw.split(","):
+        key = piece.strip()
+        if key and _KEY_RE.match(key):
+            out.append(key)
+    return out
+
+
+def _record_keys(state: StateInline, keys: tuple[str, ...]) -> None:
+    """Append to `state.env[ENV_KEY]` so the renderer can build a bib list."""
+    used: list[str] = state.env.setdefault(ENV_KEY, [])
+    for key in keys:
+        if key not in used:
+            used.append(key)
+
+
+def _render(keys: tuple[str, ...], bib: Bibliography) -> str:
+    parts: list[str] = []
+    for key in keys:
+        if bib.has(key):
+            entry = bib.get(key)
+            parts.append(
+                f'<a class="cite" href="#bib-{_attr(key)}" '
+                f'title="{_attr(_title(entry))}">{_text(entry.alpha_key)}</a>'
+            )
+        else:
+            parts.append(
+                f'<a class="cite cite-stale" href="#" '
+                f'title="Unknown citation key: {_attr(key)}">{_text(key)}?</a>'
+            )
+    inner = ", ".join(parts)
+    return f'<span class="cite-group">[{inner}]</span>'
+
+
+def _title(entry: Any) -> str:
+    title = entry.fields.get("title", entry.key)
+    if entry.year is not None:
+        return f"{title} ({entry.year})"
+    return title
+
+
+_ATTR = {"&": "&amp;", "<": "&lt;", '"': "&quot;"}
+_TEXT = {"&": "&amp;", "<": "&lt;", ">": "&gt;"}
+
+
+def _attr(s: str) -> str:
+    return "".join(_ATTR.get(c, c) for c in s)
+
+
+def _text(s: str) -> str:
+    return "".join(_TEXT.get(c, c) for c in s)