Skip to content
Ahmad Ammar

5. Our stack, compared

Our guides, essays and the Atmosphere handbook are written in LaTeX and built by one shared pipeline, the stack in research-helpers. Each document has a document.toml naming its chapters. From the same chapter files the stack makes the PDF (through LaTeX) and the web pages (through pandoc and the Zensical site builder), with one shared look across the site. Notebooks written as plain Python files are run where their data is, and their last run is kept in the guide’s frozen folder.

Since November 2026 GitHub builds the whole site from these sources on every push, as R for Data Science does: the repository holds sources only, and the built pages go straight to GitHub Pages.

5.1 Where we are ahead

  • One LaTeX source for print and web. Most projects start from Markdown and make the PDF second. Starting from LaTeX keeps mathematics, cross-references and print layout exact, and the web version follows.

  • Results come from code. Numbers, tables and figures in the text are generated by the notebooks, not typed, and frozen runs let a clean machine rebuild them without the data.

  • Editing tools. Every page’s Admin bar opens that chapter’s .tex, in VS Code with a PDF preview, in the browser, or in Studio, which shows the whole document with each chapter beside its rendering and lets plain paragraphs be edited in the rendering itself.

  • Publishing guard. Anything listed in .stack-hold is never built or published.

5.2 What the site does now

  • Built on GitHub from sources. .github/workflows/site.yml installs pandoc, TeX Live, Poppler and the stack on a clean Ubuntu machine, builds every guide’s PDF and pages and the site’s own pages, and deploys the result. A build takes about three minutes. An edit made anywhere, including GitHub’s web editor, goes live by itself.

  • The same PDFs everywhere. The stack ships open-licence fonts (Caladea, metric-compatible with Cambria, and Inconsolata) and loads them by path, so a PDF does not depend on fonts installed on one computer.

  • Proposed changes are built first. A pull request runs the same build and checks without publishing.

  • Checks on every build. Internal links; images without alternative text, images over 800 KB and pages without a heading (stack audit); and every outside link (lychee), reported in the run summary.

  • Upkeep that announces itself. A weekly scheduled build shows a broken toolchain or a dead link before an edit needs it, and Dependabot proposes updates to the workflow’s actions each month.

  • Report a problem. Every page links to a new GitHub issue on its document’s repository, filled in with the page’s title and address.

  • A written environment. requirements-site.txt, environment-stack.yml and python -m research_helpers.stack doctor record exactly what a build needs.

  • Citable. A CITATION.cff names how to cite the materials.

5.3 Still to do

  • Preview sites for proposed changes, as The Turing Way has, need a host that serves one copy per pull request (Netlify or Cloudflare Pages, both free for this use) and an account there.

  • Archived releases with DOIs need the repository connected to Zenodo once from a Zenodo account; tagged releases are then archived automatically.

  • The Atmosphere handbook is built from a private source and committed as built, so it is the one part that still needs the laptop.