arxiv-to-html

name

arxiv-to-html

description

End-to-end orchestrator that converts an arXiv paper into a faithful, verified, well-designed single HTML page. Runs the whole pipeline — download, macro expansion, LaTeX-to-HTML conversion, fidelity verification, and design polish — so the user does not drive each stage by hand. Use when the user runs /arxiv-to-html, or gives an arXiv id or URL (e.g. 2506.13131, hep-th/9901001, an arxiv.org link) and wants the paper converted or rendered to an HTML web page.

arxiv-to-html

Turn an arXiv paper into a faithful, verified, well-designed single HTML page — end to end.

Trigger: /arxiv-to-html <arxiv-id-or-URL> — e.g. /arxiv-to-html 2506.13131, /arxiv-to-html https://arxiv.org/abs/2506.13131, /arxiv-to-html hep-th/9901001. Also use it whenever the user supplies an arxiv id/URL and asks for an HTML or web version of the paper.

Pipeline

Five stages, run strictly in order; each reads the previous stage's output from workspace/<id>/:

[[download-arxiv]] → [[expand-latex]] → [[tex-to-html]] → [[verify-conversion]] → frontend-design

Each stage is its own skill — when you reach a stage, follow that skill's SKILL.md. This skill is the connective tissue: ordering, stage-gates, the cross-stage fixes, and the final verdict. It ships no scripts and does no conversion work itself.

Operating rules

• Track the five stages with TaskCreate so progress is visible.
• Stage-gate: after each stage, confirm its output exists and looks sane before starting the next.
• Stop on failure: if a stage cannot produce a usable output, STOP and tell the user which stage, which skill, and why — do not limp into the next stage.
• <id> is the arxiv id as normalised by download-arxiv; every artifact lives under workspace/<id>/.
• Pass the user's id/URL through verbatim — download-arxiv normalises it; do not pre-validate.

Stage 1 — download-arxiv

python .claude/skills/download-arxiv/scripts/download.py <id-or-url>

Gate: workspace/<id>/metadata.json and source/ exist. Read metadata.json.source_status — if it is pdf-only or withdrawn-or-unavailable, STOP: there is no LaTeX source and the rest of the pipeline cannot run. Otherwise continue.

Stage 2 — expand-latex

python .claude/skills/expand-latex/scripts/flatten_and_catalog.py workspace/<id>
# review workspace/<id>/macros.json  — the one judgement step
python .claude/skills/expand-latex/scripts/apply_expansion.py workspace/<id>

Default to trusting the suggested classifications. The exception worth catching: bibliography / preamble boilerplate mislabelled "simple alias" — \url, \doi, file-dependency helpers — reclassify those expand → leave (expanding \url to \texttt destroys hyperlinks; \doi often carries a conditional double-definition).

Gate: expanded.tex exists and the script's verify: line reads OK; spot-check one expanded macro. Report the expanded / dropped / left counts, any reclassifications, and any cycles.

Stage 3 — tex-to-html

Follow the [[tex-to-html]] playbook to build workspace/<id>/paper.html from expanded.tex. Two additions proven necessary beyond that skill's current steps:

• Prose rendered inside <pre> (e.g. minted escapeinside=|| regions emitted as spans) needs white-space: pre-wrap, or long lines clip silently.
• Confirm figure / equation numbers against paper.pdf before resolving \Cref/\ref — \addtocounter and \renewcommand{\thefigure} defeat counter arithmetic. (KaTeX has no equation counter at all; the tex-to-html skill numbers display equations with an explicit \tag{N} read from the PDF.)

For a paper with 100+ references or hundreds of \cites, writing a fresh, reviewed one-off script to convert the bibliography and resolve citation / cross-reference tokens is acceptable — the conversion judgement stays yours; the script only applies it mechanically.

Gate: paper.html exists with non-trivial size; Figures/ is populated; a headless render shows 0 console errors and 0 .katex-error.

Stage 4 — verify-conversion

Run both phases per [[verify-conversion]]:

python .claude/skills/verify-conversion/scripts/inventory.py workspace/<id>                                   # Phase A
workspace/.testenv/bin/python .claude/skills/verify-conversion/scripts/render_compare.py workspace/<id>        # Phase B

Phase B needs Playwright — use workspace/.testenv/bin/python if that env exists, otherwise install per the skill's SKILL.md. Many Phase A MISSING/EXTRA flags are normalisation artifacts (section-number prefixes, "Figure N |" caption prefixes, differing equation/comment counting methods) — verify each is an artifact and not a real drop, and do the prose spot-check. For Phase B, dispatch the per-element sub-agents as the skill directs.

Any genuine fault → trace it to the stage that caused it, fix it there, and re-verify. A rendering bug introduced in stage 3 is fixed in stage 3, not cosmetically patched in paper.html.

Stage 5 — frontend-design

Apply the frontend-design skill (the official Anthropic plugin) to make paper.html distinctive and polished. Preserve every correctness layer from stage 3 — the KaTeX assets and render script, fitWideEquations, the overflow CSS (.table-wrap, .equation, .figpair, overflow-wrap), white-space:pre-wrap on prose, the diff colorizer. Re-skinning is welcome; removing the correctness layer is a regression.

After the design pass, re-run render_compare.py (or at least sweep horizontal overflow across ~320–1440 px) — a design that re-introduces a horizontal scrollbar fails the verdict.

If the frontend-design skill is unavailable, deliver the verified functional paper.html and tell the user the design stage was skipped.

Final verdict

Report to the user:

• whether the conversion succeeded or failed;
• Phase A — coverage OK, or the specific drop / mismatch;
• Phase B — PASS or issues found; list each issue with the stage + skill responsible;
• the path to the final workspace/<id>/paper.html.

Scope

This skill only sequences and gates the existing pipeline skills — it owns no conversion mechanics. Each stage's skill owns its own playbook and scripts. If a stage's skill is missing, say so plainly rather than improvising its work.