How this project is built¶
This page explains how one set of source files becomes the website, PDFs, slides, images and calculator. It is written so that you can learn from it, or reuse it for your own project.
The idea: one source, many outputs¶
Copying text and numbers between files lets them drift apart. So each thing lives in one place, and everything else is generated.
| You edit | Which holds | It becomes |
|---|---|---|
latex/ |
The pamphlet | The PDF and the web chapters, references and appendices |
data/sialkot.json |
Shared football figures, with sources | Macros used by the pamphlet and slides |
examples/sialkot/*.tex |
The report and slides | Their PDFs |
examples/sialkot/notes.json |
Words to read aloud | PowerPoint speaker notes |
marxian/ |
Equations as Python functions | The shared figures and command line |
docs/mathematics.md, contribute.md, this page |
Pages written directly | Web pages |
Never edit docs/chapters/, docs/references.md, docs/appendix-*.md, docs/downloads/ or latex/generated/. The next build replaces them.
What happens when you change something¶
If you push to GitHub: the workflow in .github/workflows/deploy-pages.yml installs the tools, rebuilds everything, runs all the checks and publishes the site if they pass. If a check fails, the old site stays up, and GitHub shows you why under Actions.
On your own computer, nothing changes until you run the build:
python tools/build_all.py --site
To preview the result, run python -m mkdocs serve and open the address it prints.
Instagram images are made locally and committed, so that every version stays in the project's history. After a slide change, run the build and commit the new folder in examples/sialkot/instagram/. Old folders are never replaced.
A normal update, step by step¶
# 1. Change latex/content.tex
# 2. Rebuild and check everything
python tools/build_all.py --site
# 3. Review the changes
git status
git diff
# 4. Save a version with a short description
git add -A
git commit -m "Clarify the example in section 5"
# 5. Publish
git push
The tools¶
| Tool | What it does |
|---|---|
tools/build_all.py |
Runs every step below in order |
tools/sialkot.py |
Turns data/sialkot.json into LaTeX macros through marxian/ |
tools/tex_to_web.py |
Converts LaTeX to web pages with Pandoc, numbering sections, equations and citations as LaTeX does |
tools/build_pdf.py |
Compiles the PDF in a clean folder and records which source made it |
tools/build_carousel.py |
Makes the Instagram images and PowerPoint deck |
tools/make_workbook.py |
Writes the Excel calculator with live formulas |
tools/export_refs.py |
Writes data/references.ris for reference managers |
tools/check_sync.py |
Confirms that PDF, LaTeX, web pages and figures agree |
tools/check_links.py |
Tests links, anchors and references |
tools/check_arithmetic.py |
Recalculates numeric steps in equations |
tools/check_render.py |
Opens every page in a real browser, light and dark, on desktop and phone, and tests what readers see |
Going back to an earlier version¶
Git keeps every committed version. A tag names an important one.
git tag # list named versions
git checkout before-open-project-2026-11-01 # look at one
git checkout main # come back
git revert <commit> # undo a change while keeping the history
Instagram images¶
The images are 1440 by 1440 pixel PNG files. PNG suits text on a plain background, because its edges stay sharp, and Instagram recompresses every upload anyway. Instagram doesn't accept TIFF, and JPEG adds blur around text before Instagram compresses it again. A carousel can hold up to 20 images.
References¶
data/references.ris holds the pamphlet's reference list. To add it to Zotero, choose File > Import and select that file. To collect PDFs, select the items, right-click and choose Find Full Text. Some sources are paywalled, so Zotero can't fetch everything.
What goes where¶
| Project | Scope |
|---|---|
| This repository | The pamphlet, its example, and tools that know about them |
| research-helpers | General tools for any project, such as converting LaTeX to Word and PDF slides to images and PowerPoint |
The rule: if a tool would help a stranger with a different project, it belongs in research-helpers. If it needs to know about this pamphlet, it stays here.
What the checks cannot do¶
They confirm that the outputs agree, the sums add up and the pages display properly. They can't tell you that an argument is right, or that a source says what is claimed. That takes readers, which is why your corrections matter.