Skip to content

docs: markdown panes support KaTeX ($…$ / $$…$$) but the type table doesn't say so — authors emit code-fences instead #188

Description

@ivanmkc

Observed: When authoring a markdown / panes view, equations written as code-fences (or Unicode approximations) don't typeset — because the author had no signal that real math is supported. (Context: this surfaced while an agent built a math-heavy explainer via termchart push; it defaulted to a monospace code-fence for the equations.)

Root cause: The renderer does support LaTeX math. packages/viewer/src/client/renderers/markdown.ts enables marked-katex-extension so inline $…$ and block $$…$$ typeset via KaTeX → MathML:

import markedKatex from "marked-katex-extension";
// ...
marked.use(markedKatex({ throwOnError: false, output: "mathml", nonStandard: false }));

But the top-level markdown type row in the diagram-recipes skill (plugin/skills/diagram-recipes/SKILL.md:50) presents markdown as just:

| `markdown` | formatted prose (GFM, raw HTML) | markdown text | notes, summaries, docs |

No mention of LaTeX/KaTeX/$…$. An LLM author scanning the type table to pick a renderer gets zero signal that math works, so it defaults to plain text / code-fences and the math renders as a monospace blob.

The capability is described — but only buried in the explainer-template detail file, plugin/skills/diagram-recipes/panes-explainers.md:58-63 ("LaTeX math in markdown panes … renders via KaTeX→MathML"). That's gated behind the relativity/entropy explainer recipe; an author writing a standalone markdown pane (not following that template) never reaches it. So the discoverability gap is: the authoritative type table omits math, and the one mention is context-bound.

Impact: Math-heavy explainers look broken despite the capability being present and working.

Proposed fix:

  1. Surface KaTeX in the type table. Update the markdown row in SKILL.md to read roughly: formatted prose (GFM, raw HTML, **+ LaTeX via $…$ / $$…$$ → KaTeX/MathML**). Optionally add a one-line inline example next to it. (The panes-explainers.md detail already has a good example block — the fix is mostly about making the table itself self-sufficient.)
  2. Document the $ gotchas (not currently noted anywhere):
    • Standard delimiters are in effect, so a literal currency $ should be escaped as \$.
    • Inline $…$ needs no inner whitespace adjacent to the delimiters.
  3. (verify) Output is MathML with no KaTeX CSS shipped — the renderer comment explicitly notes it ships no KaTeX web-fonts/stylesheet and relies on native MathML. Confirm equations actually render on target devices, especially iPad / Safari (native MathML support has historically been uneven). If shaky, consider output: "htmlAndMathml" and bundling the KaTeX stylesheet.

Quick repro: Push one markdown pane with $$\frac{a}{b}$$ and another with the same inside a code-fence — the first typesets, the second doesn't, and nothing in the type table tells you the first will work.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions