Repository navigation
Fix maths markup so the book builds as PDF via LaTeX - #3
Merged
Merged
Conversation
shorttle
commented
Oct 8, 2026
shorttle
commented
Contributor
- Fix maths markup so the book builds as PDF via LaTeX
- Document the PDF build route and drop the unused pyppeteer dependency
- Build the book on pull requests without deploying
The notes were written against MathJax, which accepts plain-TeX and
MathJax-only idioms that real LaTeX rejects. The HTML build never
complained, so these accumulated silently and `--builder pdflatex`
failed with 163 hard errors. LaTeX halts at the first error, so each
build only exposed the next one.
Seven root causes (the rest were cascades):
* \lt and \gt are MathJax-only -> \providecommand in the preamble
* \ce{} / \pu{} had no LaTeX package -> \usepackage{mhchem}
* \newcommand{\ee} repeated in-document -> moved to config, both outputs
* \eqalignno{} / \eqalign{} are plain TeX -> aligned
* \cr inside align -> \\
* & placed inside \ce{} -> moved outside
* _\ce{AB} and ^\ddagger unbraced -> braced
\pu has no LaTeX equivalent (mhchem v4.10 does not define it), so its one
use is now written in plain math.
mathjax3_config also needs 'configmacros' in tex.packages: that list is a
replacement, not an addition, and without it MathJax silently ignores the
macros block and \ee renders as "Undefined control sequence".
makefile: `make pdf` now uses the LaTeX builder (needs MacTeX/TeX Live).
The old pdfhtml route is kept as `make pdfhtml` but is broken -- pyppeteer
calls websockets.client.connect, which websockets >= 10 no longer exposes
as a bare attribute.
Verified: PDF builds to 464 pages with 0 LaTeX errors, structurally
validated with ghostscript. HTML output diffed against a pristine baseline
across all 66 pages -- no rendering differences, 0 MathJax errors, and
equation numbering unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
pyppeteer was only ever needed by the pdfhtml builder, which is broken, so remove it from both requirements files. The makefile comment on the pdfhtml target is updated to say the target will now fail at import. Add a "Building a PDF" section to the README covering the TeX prerequisite (xelatex and latexmk, via MacTeX or TeX Live), which is not obvious from the Python dependencies alone, and the expected output. Also record the maths constructs that render under MathJax but break the LaTeX build. These fail silently in the HTML build, which is how they accumulated in the first place. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The workflow only ran on push to main, so there was no way to check that a branch builds before it went live. Add a pull_request trigger covering the same build steps. The deploy step is guarded on the event being a push to main. Without that guard the new trigger would publish a pull request's branch straight to gh-pages, which is the opposite of the intent. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.