simplex-web 0.2.0__py3-none-any.whl

simplex/web/equations.py

@@ -0,0 +1,79 @@
+r"""Display-equation tags + cross-references.
+
+Authors write standard LaTeX ``\tag{X}`` inside ``$$...$$`` (or already-
+rewritten ``\[...\]``). We pull the tag out of the math content server-side
+and emit a layout we control:
+
+    <div class="equation" id="eq-X">
+      <div class="math block">\[ ...math without \tag... \]</div>
+      <span class="eq-tag">(X)</span>
+    </div>
+
+Why move the tag out of the math:
+
+1. ``\ref{eq-X}`` cross-references need a stable anchor on a DOM element
+   that doesn't get re-rendered by KaTeX.
+2. KaTeX positions its built-in ``\tag`` absolutely at ``right: 0`` of
+   the math element. When ``notes.js`` scales a wide equation to fit
+   the column, the absolute tag rides inside the scaled box and ends
+   up overlapping the formula. A grid-laid sibling stays at natural
+   size, in its own column.
+
+The returned `labels` map (``"eq-3" -> "(3)"``) is consumed by
+``callouts.transform`` so ``\ref{eq-3}`` resolves to the linked
+display text.
+"""
+
+import re
+
+# Match a `<div class="math block">\[...\]</div>` produced by dollarmath +
+# the renderer in `notes.py`.
+_BLOCK_RE = re.compile(
+    r'<div class="math block">\s*\\\[(?P<math>.*?)\\\]\s*</div>',
+    re.DOTALL,
+)
+_TAG_RE = re.compile(r"\\tag\{(?P<label>[^}]+)\}")
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+_ESCAPE = {"&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;"}
+
+
+def _escape(s: str) -> str:
+    return "".join(_ESCAPE.get(c, c) for c in s)
+
+
+def transform(html: str) -> tuple[str, dict[str, str]]:
+    """Extract ``\\tag{}`` from each display math block.
+
+    Returns ``(rewritten_html, labels)`` where ``labels`` maps each
+    ``eq-<slug>`` to its display string ``"(<original tag>)"``.
+    """
+    labels: dict[str, str] = {}
+    # Track slug collisions: two equations both tagged `\tag{3}` get
+    # `eq-3` and `eq-3-2`. Stable across a single build.
+    used_slugs: dict[str, int] = {}
+
+    def replace(match: re.Match[str]) -> str:
+        math = match.group("math")
+        tag_match = _TAG_RE.search(math)
+        if not tag_match:
+            return match.group(0)
+        label = tag_match.group("label").strip()
+        slug_base = _SLUG_RE.sub("-", label.lower()).strip("-") or "tag"
+        count = used_slugs.get(slug_base, 0) + 1
+        used_slugs[slug_base] = count
+        slug = slug_base if count == 1 else f"{slug_base}-{count}"
+        eq_id = f"eq-{slug}"
+        display = f"({label})"
+        labels[eq_id] = display
+
+        clean_math = _TAG_RE.sub("", math).rstrip()
+        return (
+            f'<div class="equation" id="{_escape(eq_id)}">'
+            f'<div class="math block">\\[{clean_math}\\]</div>'
+            f'<span class="eq-tag">{_escape(display)}</span>'
+            f"</div>"
+        )
+
+    new_html = _BLOCK_RE.sub(replace, html)
+    return new_html, labels

simplex/web/notes.py

@@ -0,0 +1,135 @@
+r"""Render a deck's notes.md (or a raw markdown string) to academic-style HTML.
+
+Pipeline:
+
+1. markdown-it (commonmark) + plugins:
+   - ``dollarmath_plugin``  -- ``$...$`` / ``$$...$$`` -> KaTeX-friendly
+     ``\(...\)`` / ``\[...\]``.
+   - ``footnote_plugin``    -- ``^[note]`` inline notes (Tufte sidenotes).
+   - ``anchors_plugin``     -- heading anchors for deep linking.
+   - ``slide_ref``          -- ``[slide:N]`` -> in-page clickable jumps.
+   - ``cite``               -- ``\cite{key1,key2}`` -> alpha-tag bibliography
+     links; cited keys collected on ``state.env["citations"]``.
+2. Pygments syntax highlight for fenced code blocks (DarculaStyle).
+3. Post-process footnote HTML into Tufte sidenote markup
+   (`web/sidenotes.py`).
+4. Append the rendered bibliography (``<ol class="bib-list">``) when a
+   ``Bibliography`` was supplied and any keys were cited.
+
+Math (``$...$`` / ``$$...$$``) is rewritten with KaTeX-friendly ``\\(...\\)``
+and ``\\[...\\]`` delimiters so katex auto-render (loaded in base.html) can
+typeset it client-side. Fenced code blocks are highlighted server-side with
+Pygments using the same DarculaStyle the video engine uses, so notes match
+the slides visually.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from markdown_it import MarkdownIt
+from mdit_py_plugins.anchors import anchors_plugin
+from mdit_py_plugins.dollarmath import dollarmath_plugin
+from mdit_py_plugins.footnote import footnote_plugin
+from pygments import highlight as _pyg_highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import get_lexer_by_name, guess_lexer
+from pygments.util import ClassNotFound
+
+from simplex.theme.pygments_style import DarculaStyle
+from simplex.web import callouts, equations, sidenotes
+from simplex.web.bibliography import Bibliography
+from simplex.web.citations import ENV_KEY as _CITE_ENV_KEY
+from simplex.web.citations import make_plugin as cite_plugin
+from simplex.web.refs import make_plugin as ref_plugin
+from simplex.web.slide_ref import make_plugin as slide_ref_plugin
+
+
+def _math_renderer(content: str, options: dict[str, Any]) -> str:
+    content = content.strip()
+    if options.get("display_mode"):
+        return f"\\[{content}\\]"
+    return f"\\({content}\\)"
+
+
+# `nowrap=True` strips the Pygments <div><pre> wrap so markdown-it's own
+# <pre><code> is the only wrap. The Darcula background lives on
+# `.deck-notes pre` in simplex.css.
+_FORMATTER = HtmlFormatter(nowrap=True, noclasses=True, style=DarculaStyle)
+
+
+def _highlight(code: str, lang: str, _attrs: str) -> str:
+    try:
+        lexer = get_lexer_by_name(lang) if lang else guess_lexer(code)
+    except ClassNotFound:
+        return ""  # markdown-it falls back to its default <pre><code>
+    return _pyg_highlight(code, lexer, _FORMATTER)
+
+
+def _make(
+    slide_count: int | None = None,
+    bibliography: Bibliography | None = None,
+) -> MarkdownIt:
+    md = MarkdownIt(
+        "commonmark",
+        {
+            "html": False,
+            "linkify": True,
+            "typographer": True,
+            "highlight": _highlight,
+        },
+    )
+    md.enable("table")
+    md.use(dollarmath_plugin, allow_labels=True, renderer=_math_renderer)
+    # `inline=True` enables `^[note]` inline footnotes -- post-processed into
+    # Tufte sidenotes by `sidenotes.transform`.
+    md.use(footnote_plugin, inline=True, move_to_end=True)
+    md.use(anchors_plugin, max_level=3)
+    md.use(slide_ref_plugin(slide_count=slide_count))
+    md.use(cite_plugin(bibliography))
+    md.use(ref_plugin())
+    return md
+
+
+def render_text(
+    markdown: str,
+    *,
+    slide_count: int | None = None,
+    bibliography: Bibliography | None = None,
+) -> str:
+    """Render a markdown string to academic-style HTML.
+
+    Pass `bibliography` to enable `\\cite{key}` -> linked alpha tags and a
+    trailing ``<section class="bibliography">``. When omitted, ``\\cite{}``
+    markers render as the literal `[key?]` "stale" tags.
+    """
+    md = _make(slide_count=slide_count, bibliography=bibliography)
+    env: dict[str, Any] = {}
+    body = md.render(markdown, env)
+    body = sidenotes.transform(body)
+    # Equations first so the labels they emit are visible to the callouts
+    # pass, which resolves every `\ref{...}` placeholder in one walk.
+    body, eq_labels = equations.transform(body)
+    # Callouts after sidenotes so blockquote-shaped sidenotes (unlikely but
+    # possible) don't get mis-rewritten; before bibliography so `\ref{}`
+    # placeholders that point at callouts (or equations) can be resolved
+    # while we're still walking the body.
+    body = callouts.transform(body, extra_labels=eq_labels)
+    if bibliography is not None:
+        used = tuple(env.get(_CITE_ENV_KEY, []))
+        if used:
+            body += bibliography.to_html(used)
+    return body
+
+
+def render(
+    notes_md: Path,
+    *,
+    slide_count: int | None = None,
+    bibliography: Bibliography | None = None,
+) -> str:
+    """Render a notes.md file to HTML."""
+    return render_text(
+        notes_md.read_text(encoding="utf-8"),
+        slide_count=slide_count,
+        bibliography=bibliography,
+    )

simplex/web/refs.py

@@ -0,0 +1,60 @@
+r"""markdown-it-py plugin -- `\ref{id}` -> cross-reference placeholder.
+
+Emits ``<a class="ref" data-simplex-ref="id" href="#id">id</a>``. The
+callouts post-processor (`web/callouts.py`) resolves the placeholder to
+the proper display label (`Theorem 3.1`) once block IDs are known.
+
+Mirrors `\cite{...}`: registered *before* `escape` so the leading
+backslash survives, advances `state.pos` in silent mode so caller
+loops (`parseLinkLabel`, used by inline footnotes) terminate.
+"""
+
+import re
+from typing import Any
+
+from markdown_it import MarkdownIt
+from markdown_it.rules_inline import StateInline
+
+NAME = "ref"
+
+# `\ref{id}` -- id can include letters, digits, dashes, dots, colons, slashes.
+_PATTERN = re.compile(r"\\ref\{([A-Za-z0-9_:\-./]+)\}")
+
+
+def make_plugin() -> Any:
+    """Return a markdown-it plugin emitting cross-reference placeholders."""
+
+    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
+            if silent:
+                state.pos = match.end()
+                return True
+            ref_id = match.group(1)
+            token = state.push("html_inline", "", 0)
+            token.content = (
+                f'<a class="ref" data-simplex-ref="{_attr(ref_id)}" '
+                f'href="#{_attr(ref_id)}">{_text(ref_id)}</a>'
+            )
+            state.pos = match.end()
+            return True
+
+        md.inline.ruler.before("escape", NAME, rule)
+
+    return plugin
+
+
+_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)

simplex/web/sidenotes.py

@@ -0,0 +1,76 @@
+"""Tufte-style sidenotes via `mdit-py-plugins`'s ``footnote_plugin``.
+
+Authors write ``^[some marginal aside]`` inline. Internally markdown-it emits
+the standard footnote markup (`<sup class="footnote-ref">` + a
+``<section class="footnotes">`` at the bottom). We post-process that HTML so
+each footnote body floats next to its anchor as a Tufte-style sidenote:
+
+    text<sup class="sidenote-ref" id="snref-1">1</sup><aside
+        class="sidenote" id="sn-1" role="note">body</aside> more text.
+
+The bottom ``<section class="footnotes">`` is removed so wide-screen readers
+see only the marginal note; narrow screens collapse the sidenote inline (via
+CSS in ``static/simplex.css``).
+
+Pure HTML transformation -- no JS, no token-tree gymnastics. This keeps the
+markdown-it plugin chain (footnotes + dollarmath + citations + slide-ref)
+working without conflicts.
+"""
+
+import re
+
+# Matches one <li id="fnN" ...>...</li>, capturing the id and the inner HTML
+# (greedy enough to span nested tags, lazy enough to stop at the next list
+# item). We rely on the footnote plugin's stable shape.
+_LI_RE = re.compile(
+    r'<li\s+id="fn(?P<n>\d+)"[^>]*>\s*(?P<body>.*?)\s*</li>',
+    re.DOTALL,
+)
+_REF_RE = re.compile(
+    r'<sup\s+class="footnote-ref">\s*<a[^>]*href="#fn(?P<n>\d+)"[^>]*>\[(?P<num>\d+)\]</a>\s*</sup>',
+)
+_BACKREF_RE = re.compile(r'\s*<a[^>]*class="footnote-backref"[^>]*>[^<]*</a>')
+_SECTION_RE = re.compile(
+    r'<hr\s+class="footnotes-sep"\s*/?>\s*<section\s+class="footnotes">.*?</section>',
+    re.DOTALL,
+)
+_OUTER_P_RE = re.compile(r"^\s*<p>(.*)</p>\s*$", re.DOTALL)
+
+
+def transform(html: str) -> str:
+    """Rewrite footnote markup in ``html`` into Tufte sidenote markup."""
+    bodies = _extract_bodies(html)
+    if not bodies:
+        return html
+    html = _SECTION_RE.sub("", html)
+
+    def replace_ref(match: re.Match[str]) -> str:
+        n = match.group("n")
+        num = match.group("num")
+        body = bodies.get(n, "")
+        return _render_sidenote(n, num, body)
+
+    return _REF_RE.sub(replace_ref, html)
+
+
+def _extract_bodies(html: str) -> dict[str, str]:
+    bodies: dict[str, str] = {}
+    for match in _LI_RE.finditer(html):
+        n = match.group("n")
+        body = _BACKREF_RE.sub("", match.group("body"))
+        # Footnote bodies are wrapped in a <p>; for an inline sidenote we want
+        # the inner content, not a block-level <p>.
+        single_para = _OUTER_P_RE.match(body)
+        if single_para:
+            body = single_para.group(1)
+        bodies[n] = body.strip()
+    return bodies
+
+
+def _render_sidenote(n: str, num: str, body: str) -> str:
+    return (
+        f'<label for="sn-toggle-{n}" class="sidenote-ref" id="snref-{n}">{num}</label>'
+        f'<input type="checkbox" id="sn-toggle-{n}" class="sidenote-toggle" '
+        'aria-hidden="true" />'
+        f'<aside class="sidenote" id="sn-{n}" role="note">{body}</aside>'
+    )

simplex/web/site_config.py

@@ -0,0 +1,71 @@
+"""Site-wide configuration: committed `site.toml` merged with env overrides.
+
+`site.toml` (in git) carries brand/nav/section ordering.
+Env (`SIMPLEX_GA_TAG`, `SIMPLEX_BASE_URL`, `SIMPLEX_BRAND`, `SIMPLEX_PREVIEW`)
+carries deployment concerns and is never committed.
+"""
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any, Self
+
+from pydantic import BaseModel, ConfigDict
+
+
+class NavLink(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    label: str
+    href: str
+
+
+class SiteConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    brand: str = "Simplex"
+    tagline: str | None = None
+    nav: tuple[NavLink, ...] = ()
+    default_section_order: tuple[str, ...] = ()
+
+    # Deployment-only fields (loaded from env, not committed).
+    ga_tag: str = ""
+    base_url: str = "/"
+    preview: bool = False
+
+    @property
+    def ga_enabled(self) -> bool:
+        return bool(self.ga_tag) and not self.preview
+
+    def url(self, path: str) -> str:
+        """Resolve a site-relative path against `base_url`."""
+        base = self.base_url.rstrip("/")
+        clean = path.lstrip("/")
+        if not base:
+            return f"/{clean}"
+        return f"{base}/{clean}"
+
+    @classmethod
+    def load(cls, repo_root: Path | None = None) -> Self:
+        repo_root = repo_root or Path.cwd()
+        committed: dict[str, Any] = {}
+        toml_path = repo_root / "site.toml"
+        if toml_path.exists():
+            committed = dict(tomllib.loads(toml_path.read_text(encoding="utf-8")))
+            nav_raw = committed.pop("nav", ()) or ()
+            if isinstance(nav_raw, list):
+                committed["nav"] = tuple(NavLink(**dict(item)) for item in nav_raw)
+            dso = committed.get("default_section_order")
+            if isinstance(dso, list):
+                committed["default_section_order"] = tuple(dso)
+
+        env_overrides: dict[str, Any] = {}
+        if (ga := os.environ.get("SIMPLEX_GA_TAG")) is not None:
+            env_overrides["ga_tag"] = ga
+        if (base := os.environ.get("SIMPLEX_BASE_URL")) is not None:
+            env_overrides["base_url"] = base
+        if (brand := os.environ.get("SIMPLEX_BRAND")) is not None:
+            env_overrides["brand"] = brand
+        if (preview := os.environ.get("SIMPLEX_PREVIEW")) is not None:
+            env_overrides["preview"] = preview.lower() in {"1", "true", "yes", "on"}
+
+        return cls.model_validate(committed | env_overrides)

simplex/web/slide_ref.py

@@ -0,0 +1,54 @@
+"""markdown-it-py plugin -- ``[slide:N]`` => clickable jump anchor.
+
+Renders as ``<a href="#" class="slide-ref" data-slide="{N}">N</a>``. The
+parent viewer.js (see ``web/static/viewer.js``) binds clicks and forwards
+``{type: 'simplex.goto', idx: N}`` to the iframe, which subtracts one to
+reach Reveal's 0-based horizontal index. The 1-based convention here
+matches the sidebar's ``data-slide-target`` (= ``MainSlide.index``) so
+both navigation paths speak the same vocabulary.
+
+If ``slide_count`` is provided and N is out of range, the anchor is emitted
+with the extra class ``slide-ref-stale`` so the build flags it visually
+without breaking the page.
+"""
+
+import re
+from typing import Any
+
+from markdown_it import MarkdownIt
+from markdown_it.rules_inline import StateInline
+
+NAME = "slide_ref"
+_PATTERN = re.compile(r"\[slide:(\d+)\]")
+
+
+def make_plugin(slide_count: int | None = None) -> Any:
+    """Return a markdown-it plugin bound to a slide count for validation."""
+
+    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
+            # Silent / validation mode: must still advance `state.pos` past
+            # the match so callers like `parseLinkLabel` don't loop forever.
+            if silent:
+                state.pos = match.end()
+                return True
+            n = int(match.group(1))
+            stale = slide_count is not None and (n < 1 or n > slide_count)
+            token = state.push("html_inline", "", 0)
+            classes = "slide-ref" + (" slide-ref-stale" if stale else "")
+            title = "Slide out of range" if stale else f"Jump to slide {n}"
+            token.content = (
+                f'<a href="#" class="{classes}" data-slide="{n}" '
+                f'role="button" aria-label="{title}" title="{title}">{n}</a>'
+            )
+            state.pos = match.end()
+            return True
+
+        md.inline.ruler.before("link", NAME, rule)
+
+    return plugin

simplex/web/static/README.md

@@ -0,0 +1,23 @@
+# web/static/
+
+Vendored runtime assets, copied verbatim to `site/static/` at build time.
+
+## Committed
+
+- `simplex.css` -- site-specific styles (carousel, deck page, academic
+  notes typography, Tufte sidenotes, citations, bibliography).
+- `viewer.js` -- parent-page bridge for the deck iframe + carousel arrows.
+
+## Vendored for builds (not committed)
+
+- `tailwind.js` (Tailwind Play CDN -- JIT runtime, required for arbitrary-value classes)
+- `katex/` (CSS + fonts + JS + auto-render)
+- `reveal.js/` (`reveal.js`, `reveal.css`, `reset.css`)
+- `htmx.min.js` (optional, kept for future progressive enhancement)
+- `fonts/lato/` -- Lato 400/700/900 + italics (UI + headings)
+- `fonts/merriweather/` -- Merriweather 400/700/900 + italics (body notes)
+
+## Don't
+
+- Don't load these via CDN -- vendoring keeps Pages offline-safe.
+- Don't edit the vendored files; upgrade them with `scripts/vendor.sh`.