In LA TEX a book is one document: chapter 3 can refer to a theorem in chapter 1, continues the numbering where chapter 2 stopped, and uses macros defined earlier. On the web the same book is usually split over several pages or tabs. A batch gives you both. All blocks with the same batch= are compiled together as one document, in the order of their weight=, and each block shows only its own part.
Here is a small book of three chapters, each shown in a tab of its own. Chapter 2 uses the macro \N that chapter 1 defined and refers to its theorem and equation; chapter 3 names theorems from both earlier chapters. All numbers are the book’s.
Chapter 1
Counting
We count with the natural numbers, and prove things about them by induction.
Theorem 1.1. If a property holds for, and holds forwhenever it holds for, then it holds for every.
Chapter 2
Sums
This chapter is compiled together with the first one, so it can use, which chapter 1 defined, and refer back to it: by Theorem 1.1, equation (1.1) holds for every.1
1 The induction step addsto both sides.
Theorem 2.1. For every,
Its number continues the book’s own count: chapter 2, first theorem.
Chapter 3
Beyond
Theorems 1.1 and 2.1 are in the two earlier chapters, and their numbers are correct here because the book was compiled as one document.
Theorem 3.1. There is no largest.
Proof. Ifwere largest,would be larger.
How the example is made
Four files and one build command. The chapters are ordinary .tex files without a preamble, in a directory the build is told about; the book’s preamble sits beside them, and every block names it with preamble=, a path from the site’s root:
website/ the Hugo site
├── content/docs/getting-started/
│ └── books.md this page: the shortcodes below
└── layouts/shortcodes/
├── latex.html from integrations/hugo
└── tabs.html, tab.html this site's tabs (optional)
examples/book/ --demos-dir: where file="…" is found
├── preamble.tex preamble="../examples/book/preamble.tex"
├── chapter1.tex
├── chapter2.tex
└── chapter3.tex
The build is given that directory, and compiles the three chapters as one book:
node integrations/hugo/prebuild.ts website --demos-dir examples/book
hugo --source website
\chapter{Counting}\newcommand{\N}{\mathbb{N}}We count with the natural numbers $\N=\{0, 1, 2, \dots\}$, and prove
things about them by induction.
\begin{theorem}\label{thm:induction}If a property holds for $0$, and holds for $n+1$ whenever it holds for $n$,
then it holds for every $n \in\N$.
\end{theorem}\begin{equation}\label{eq:gauss} 0 + 1 + \dots + n = \frac{n(n+1)}{2}.
\end{equation}
\chapter{Sums}This chapter is compiled together with the first one, so it can use
$\N$, which chapter~1 defined, and refer back to it: by
Theorem~\ref{thm:induction}, equation~\eqref{eq:gauss} holds for every
$n \in\N$.\footnote{The induction step adds $n+1$ to both sides.}\begin{theorem}\label{thm:squares}For every $n \in\N$,
\[0^2+1^2+\dots+ n^2=\frac{n(n+1)(2n+1)}{6}. \]\end{theorem}Its number continues the book's own count: chapter~2, first theorem.
\chapter{Beyond}Theorems~\ref{thm:induction} and~\ref{thm:squares} are in the two earlier
chapters, and their numbers are correct here because the book was
compiled as one document.
\begin{theorem}There is no largest $n \in\N$.
\end{theorem}\begin{proof}If $n$ were largest, $n +1\in\N$ would be larger.
\end{proof}
% Accessible formulas: tagging on and luamml loaded, so that LaTeX writes
% every formula's MathML (with classic fonts LaTeX loads luamml only when
% asked). Reflow TeX reads it for screen readers.
\DocumentMetadata{tagging=on}\tagpdfsetup{math/mathml/luamml/load=true}% The preamble of the example book (website: docs/getting-started/books),
% where every chapter's block names it: preamble="../examples/book/preamble.tex".
% (The static-site build, build.py examples/book --batch, takes a directory's
% preamble.tex by itself.) A real book class, so \chapter works and numbers
% theorems and equations per chapter.
\documentclass{book}% Character protrusion and font expansion, as in the PDF: the viewer
% protrudes and expands as the document says, and only then.
\usepackage{microtype}\usepackage{amsthm}\newtheorem{theorem}{Theorem}[chapter]
\usepackage[boxed]{reflowtex}% Section headings ragged right: at a narrow measure a heading breaks onto
% several lines, and the standard classes would justify them. Only the
% heading's style changes, not its spacing or font.
\usepackage{etoolbox}\makeatletter\patchcmd{\@sect}{\begingroup #6}{\begingroup #6\raggedright}{}{}\patchcmd{\@ssect}{\begingroup #4}{\begingroup #4\raggedright}{}{}\makeatother
The tabs are this site’s own shortcodes (tabs and tab, a few lines each); nothing in the batch depends on them. The same three latex lines could just as well be on three different pages, one chapter each.
How it works
prebuild.ts collects every block of a batch – across all pages – orders them by weight (ties go by page, then by position on the page), and compiles them as one document, as if a main.tex had \included them in that order. Between the parts it places a marker that opens no group, so whatever one part defines is still defined in the next. The finished document is then cut back into one block per part, each carrying only its own paragraphs, footnotes, pictures and labels.
One chapter, two places. A block may repeat a chapter the batch already has – the same file= on another page, say. It stays one chapter of the book, compiled once, at the lowest weight= it is given, and both places show it; its labels link to the page with that lowest weight. In a different batch the same file is compiled again, as part of that book.
One preamble. All blocks of a batch use the same preamble=: a name from latex-preambles/, or, as here, a path to a .tex file from the site’s root. It may begin with its own \documentclass, here book, so \chapter works.
Any pages. The parts can sit on different pages. A reference to a label in another part becomes a link to the page that shows it, through the same link map as any other cross-reference.
Inline too. A batch block may hold its LA TEX between the shortcode’s opening and closing tags instead of naming a file.
Without Hugo. The static-site build does the same for a directory: build.py book/ --batch compiles every snippet in it, in file-name order, as one document.
Recompiled as a whole. Changing, adding or reordering any part compiles the batch again, since every part’s numbers may change.