github-math-check

Files (4)

• SKILL.md
• check-emphasis.js · scripts/
• check-github.js · scripts/
• check-local.js · scripts/

SKILL.md (first lines)

# github-math-check

**Rendering math locally proves nothing about GitHub.** GitHub transforms the math text
on its way to the client-side renderer, and the transformed string is what fails. Always
measure the delivered string.

## Known transformations (measured on live pages, 2026-07)

| written in the file | delivered to the renderer | effect |
|---|---|---|
| `\\` (row break) | `\\\` | `\begin{aligned}` rows merge → **`Missing \end{aligned}`** |
| `\\\\` | `\\\` | same |
| `\cr`, `\newline` | unchanged | ✅ use these for row breaks |
| `$\{x\}$` | `${x}$` | braces vanish (Markdown ate the escape) |
| `` $`a<b`$ `` | `$a&amp;lt;b$` | **double-escaped** → KaTeX sees `&lt;`; write `\lt` / `\gt` |
| `\tag{$x$}`, `\text{$x$}` | `\tag{\$x\$}` | `$` is escaped even inside a fence → math commands land in text mode |
| `$a \, b$` | `$a , b$` | **a stray comma is rendered** |
| `` $`\{x\}`$ ``, `` $`a \, b`$ `` | unchanged | ✅ code span is not escaped |
| ```` ```math ```` fence | contents kept, except `\\` | ✅ for display math |
| `- item` + indented ```` ```math ```` fence | `<pre lang="math">`, **not** upgraded to `<math-renderer>` | display math inside a list item shows raw LaTeX |
| `[^1]: … $\`x\`$ …` | not upgraded to `<math-renderer>` | math inside a footnote definition is not rendered |

So the safe forms are:

* display math → ```` ```math ```` fence (not `$$ … $$`)
* inline math → `` $`…`$ `` (not bare `$…$`)
* row breaks → `\cr` (never `\\`)
* `<` and `>` in **inline** math → `\lt`, `\gt` (inside a fence they are fine)
* never write `$` anywhere inside math — not in `\text{…}`, not in `\tag{…}`
* math inside a **list item** or a **footnote** → inline `` $`…`$ `` only; a ```` ```math ````
  fence there is served as a plain code block. For a long formula use
  `` $`\begin{aligned} … \cr … \end{aligned}`$ `` on its own line.

Counting catches both silently: when `check-github.js` reports **fewer** formulas than
`check-local.js`, the difference is unrendered math, not a false alarm — the page shows no
error, just raw LaTeX. Diff the two formula lists to find which ones. (Measured 2026-08 on
one file: 8 lost to list items, 5 to footnotes; both were invisible to the error count.)

## Plain-text formulas: `*` and `_` turn into italics

Not every formula goes through the math renderer. Text such as `psi(W^(W*w))`, `a*b` or
`f(_a)` written outside math and outside code — typically a generated table of notations —
is plain Markdown, and a pair of `*` or `_` becomes emphasis: the text between them is set
in italics and the delimiters disappear. Nothing reports an error. Measured with method 1,
2026-09:

| written (plain text) | GitHub renders | effect |
|---|---|---|
| `psi(W^(W*w)) = psi(psi_1(W^2*w))` | `psi(W^(W<em>w)) = psi(psi_1(W^2</em>w))` | **italics, both `*` vanish** |
| `psi(W_2+W*w)` | unchanged | fine while it is the only `*` in the cell |
| `f(_a) + g(b_)`, `(_c_)` | `f(<em>a) + g(b</em>)`, `(<em>c</em>)` | `_` next to `(` `)` or a space opens and closes emphasis |
| `psi_1(W_2) + W_w + psi_W_(w+1)(x)` | unchanged | `_` between two letters or digits never does |
| `*a` in one cell, `b*` in the next | unchanged | a table cell is parsed on its own |
| `` `psi(W^(W*w)) = …` `` | `<code>` | ✅ code span |
| `psi(W^(W\*w)) = psi(psi_1(W^2\*w))` | `*` kept | ✅ escaped, but every `*` and `_` needs it |

So:

* put formulas that are not math in a code span; inside a table cell a `|` still has to be
  written `\|`
* when the file is generated, fix the generator and regenerate — not the output

`scripts/check-emphasis.js` finds them. For every table cell (or line) it reports a `*` or
`_` that can open emphasis followed by one that can close it, by the CommonMark flanking
rules. Code spans, fences, `\*` `\_` and `**bold**` runs are skipped; emphasis across a line
break within a paragraph is not detected.

```bash
node ~/.claude/skills/github-math-check/scripts/check-emphasis.js docs
# docs/table.md:5: | A star pair | psi(W^(W*w)) = psi(psi_1(W^2*w)) |
# docs/table.md:10: | F _ after ( | f(_a) + g(b_) |
# docs/table.md:15: H paragraph: W*w + W*2 and a_(b) + (_c_)
# files : 1
# errors: 3
```

## Scripts (start here)

`scripts/check-local.js` — before pushing. Renders every formula of the given files (or
every `*.md` of a directory) with KaTeX and enforces the safe forms above.

```bash
npm install -g katex          # once
node ~/.claude/skills/github-math-check/scripts/check-local.js md/YAPSS
```

`scripts/check-github.js` — after pushing, and this is the one that decides. It fetches
the file's rendered payload from GitHub, pulls out **every** `<math-renderer>` body — the
exact string handed to the browser's renderer — and runs each through KaTeX.

```bash
node ~/.claude/skills/github-math-check/scripts/check-github.js \
     https://github.com/OWNER/REPO/blob/BRANCH/path/File.md
# url      : ...
# formulas : 2178 (84 display, 2094 inline)
# errors   : 0
```

Both exit non-zero on failure, so they can gate a commit. Green locally does **not**
imply green on GitHub — always run the second one on the pushed file.

Implementation note: request the blob URL with `Accept: application/json` and read
`payload.codeViewBlobRoute.richText`. The plain HTML page sets `richTextTruncated: true`
and `richText: null` for large files; the JSON response is never truncated.

## Method 1 — GitHub's Markdown API (fast, no push)

Shows how GitHub converts a snippet. Good for comparing two ways of writing something.

```bash
printf '%s' '{"text":"```math\n\\begin{aligned}\nA &= 1,\\cr\nB &= 2.\n\\end{aligned}\n```\n"}' > /tmp/p.json
curl -s -X POST https://api.github.com/markdown -H "Content-Type: application/json" --data @/tmp/p.json
```

Read the HTML it returns: `<pre lang="math"><code>…</code></pre>` for a fence,
`$<code>…</code>$` for `` $`…`$ ``. Check that backslashes and escapes survived.

⚠ The API does **not** reproduce the `\\` → `\\\` step, which happens in the blob-page
pipeline. Use method 2 for that.

From koteitan/my-skills, MIT.

More from koteitan/my-skills