mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-05-07 18:18:42 -05:00
0f704b8023
Wave 4 editorial content across 20 modules + new glossary back matter:
1. Module opener hooks (20 new 2-3 sentence paragraphs between the
chapter heading and Module Info callout). Every hook LEADS with
the systems angle (memory, bandwidth, arithmetic intensity,
cache, HBM, roofline, KV cache, hardware utilization, etc.) and
connects back to the ML story. Reinforces that this is a lab
guide for ML systems, not an ML-theory textbook.
2. Code-listing captions on substantive code blocks (roughly >10
lines, defines a class/function/algorithm). Populates Quarto's
List of Listings front matter. Combined across F1/F2/L/O
subagent waves: roughly 60 listings now carry
'**Listing N.M — Brief description**' captions.
3. Figure alt-text audit across 20 module diagrams. Most already
carried objective specific alt-text; a handful were rewritten
for precision.
4. Glossary at back matter (tinytorch/quarto/glossary.qmd + registered
in pdf/_quarto.yml). 90 alphabetical entries spanning tensor /
memory / autograd / training / architecture / optimization
terms. One-sentence definitions. Module cross-references where
the term is central. Lab-guide voice, not dictionary.
5. Style discipline: no em-dashes in prose (caption templates
'— Description' are the only exception, required by parser).
All agent outputs and the hand-revised hooks audited for em-dash
use.
6. SVG trailing-newline hygiene: 8 SVGs touched by the Gemini style
audit had lost their trailing newline. Restored per the SVG
file-hygiene rule.
584 lines
28 KiB
YAML
584 lines
28 KiB
YAML
# =============================================================================
|
||
# TINYTORCH LAB GUIDE — QUARTO BOOK (PDF)
|
||
# =============================================================================
|
||
# Produces the bundled PDF that's injected into the live site as
|
||
# mlsysbook.ai/tinytorch/assets/downloads/TinyTorch-Guide.pdf.
|
||
#
|
||
# This project lives alongside the website config (quarto/_quarto.yml)
|
||
# and reuses its .qmd chapter files via relative paths. The website is a
|
||
# `project: website`; the PDF is a `project: book`. They share sources.
|
||
#
|
||
# Why a subdirectory (not a second format on the website project):
|
||
# Quarto's website project emits one HTML file per .qmd. To get a single
|
||
# bundled PDF covering all chapters we need `project: book`, which is a
|
||
# different project type and therefore lives in its own config.
|
||
# =============================================================================
|
||
|
||
project:
|
||
type: book
|
||
# Render output goes to the parent's _build/pdf/ so the injection path
|
||
# in tinytorch-publish-live.yml (assets/downloads/TinyTorch-Guide.pdf)
|
||
# can stay keyed off vars.TINYTORCH_SITE.
|
||
output-dir: _build
|
||
|
||
# Pages live one level up (in the website source tree) so we can reuse
|
||
# them without symlinks or copies. Relative paths resolve from this
|
||
# file's directory, i.e., tinytorch/quarto/pdf/.
|
||
book:
|
||
title: "TinyTorch Lab Guide"
|
||
subtitle: "Don't just `import torch`. Build it."
|
||
author: "Prof. Vijay Janapa Reddi (Harvard University)"
|
||
date: today
|
||
# Artifact filename the publish workflow injects as
|
||
# assets/downloads/TinyTorch-Guide.pdf. Quarto book projects derive
|
||
# the PDF filename from `title:` by default (→ "TinyTorch-Lab-Guide"),
|
||
# so we override. Value is the stem only — Quarto appends the format
|
||
# extension, so ".pdf" here produces the double-dotted file.
|
||
output-file: TinyTorch-Guide
|
||
# The chapters below intentionally match the legacy _toc_pdf.yml scope:
|
||
# preface + big-picture + getting-started, then the 20 modules in tier
|
||
# order, then a closing conclusion. No tier-overview or landing pages —
|
||
# those are website-only content with grids and cards that don't print.
|
||
chapters:
|
||
- index.qmd
|
||
- ../preface.qmd
|
||
- ../big-picture.qmd
|
||
- ../getting-started.qmd
|
||
- part: "Foundation Tier"
|
||
chapters:
|
||
- ../modules/01_tensor.qmd
|
||
- ../modules/02_activations.qmd
|
||
- ../modules/03_layers.qmd
|
||
- ../modules/04_losses.qmd
|
||
- ../modules/05_dataloader.qmd
|
||
- ../modules/06_autograd.qmd
|
||
- ../modules/07_optimizers.qmd
|
||
- ../modules/08_training.qmd
|
||
# Milestones are interleaved between tiers so each one lands as soon as
|
||
# the prerequisite modules are complete. Each milestone recreates a
|
||
# historical breakthrough using the components built in the prior tier.
|
||
- part: "Foundation Milestones"
|
||
chapters:
|
||
- ../milestones/index.qmd
|
||
- ../milestones/01_perceptron.qmd
|
||
- ../milestones/02_xor.qmd
|
||
- ../milestones/03_mlp.qmd
|
||
- part: "Architecture Tier"
|
||
chapters:
|
||
- ../modules/09_convolutions.qmd
|
||
- ../modules/10_tokenization.qmd
|
||
- ../modules/11_embeddings.qmd
|
||
- ../modules/12_attention.qmd
|
||
- ../modules/13_transformers.qmd
|
||
- part: "Architecture Milestones"
|
||
chapters:
|
||
- ../milestones/04_cnn.qmd
|
||
- ../milestones/05_transformer.qmd
|
||
- part: "Optimization Tier"
|
||
chapters:
|
||
- ../modules/14_profiling.qmd
|
||
- ../modules/15_quantization.qmd
|
||
- ../modules/16_compression.qmd
|
||
- ../modules/17_acceleration.qmd
|
||
- ../modules/18_memoization.qmd
|
||
- ../modules/19_benchmarking.qmd
|
||
- part: "Optimization Milestones"
|
||
chapters:
|
||
- ../milestones/06_mlperf.qmd
|
||
- part: "Capstone"
|
||
chapters:
|
||
- ../modules/20_capstone.qmd
|
||
- ../conclusion.qmd
|
||
- ../glossary.qmd
|
||
|
||
# Default format is PDF — this project exists only to produce the guide.
|
||
# HTML output is handled by the sibling website project.
|
||
format:
|
||
pdf:
|
||
# NB: output filename is pinned via `book.output-file` above —
|
||
# `format.pdf.output-file` is silently ignored for book projects.
|
||
# Standard LaTeX `book` class rather than KOMA-script's scrreprt:
|
||
# titlesec (which we use for custom chapter/section formatting)
|
||
# does not recognise KOMA's sectioning command internals and
|
||
# silently no-ops the formatting, breaking the downstream \begin{document}.
|
||
documentclass: book
|
||
papersize: letter
|
||
geometry:
|
||
- inner=1in
|
||
- outer=1in
|
||
- top=1in
|
||
- bottom=1in
|
||
# XeLaTeX handles Unicode (emojis in chapter titles etc.) without the
|
||
# package-juggling that pdfLaTeX requires. Matches the legacy build.
|
||
pdf-engine: xelatex
|
||
# ── TeX Gyre font stack — parity with the legacy jupyter-book PDF.
|
||
# Pagella: Palatino-equivalent old-style serif (warm, academic).
|
||
# Heros: Helvetica-equivalent sans for running heads.
|
||
# Cursor: Courier-equivalent monospace for code, scaled to 88%.
|
||
#
|
||
# Referenced by filename (not PostScript name) so kpsewhich resolves
|
||
# them directly from TEXMFDIST. The name-based form
|
||
# (mainfont: "TeX Gyre Pagella") fails on macOS because Core Text
|
||
# doesn't see TeX Live's private font tree; the file-based form
|
||
# works identically on macOS and the Ubuntu CI runner.
|
||
mainfont: "texgyrepagella"
|
||
mainfontoptions:
|
||
- "Extension=.otf"
|
||
- "UprightFont=*-regular"
|
||
- "BoldFont=*-bold"
|
||
- "ItalicFont=*-italic"
|
||
- "BoldItalicFont=*-bolditalic"
|
||
- "Ligatures=TeX"
|
||
sansfont: "texgyreheros"
|
||
sansfontoptions:
|
||
- "Extension=.otf"
|
||
- "UprightFont=*-regular"
|
||
- "BoldFont=*-bold"
|
||
- "ItalicFont=*-italic"
|
||
- "BoldItalicFont=*-bolditalic"
|
||
monofont: "texgyrecursor"
|
||
monofontoptions:
|
||
- "Extension=.otf"
|
||
- "UprightFont=*-regular"
|
||
- "BoldFont=*-bold"
|
||
- "ItalicFont=*-italic"
|
||
- "BoldItalicFont=*-bolditalic"
|
||
- "Scale=0.88"
|
||
toc: true
|
||
toc-depth: 2
|
||
# List of Figures and List of Tables in front matter. Professional
|
||
# textbooks (H&P, CLRS, Swift Book) carry these as a reader aid;
|
||
# they cost one page each and make the figures/tables in this
|
||
# 350-page guide genuinely navigable.
|
||
lof: true
|
||
lot: true
|
||
number-sections: true
|
||
# Line spacing: 1.1× the font's natural leading. Palatino's
|
||
# natural leading at 11pt is ~13.2pt; this bumps to ~14.5pt.
|
||
# Sweet spot for long-session lab-book reading — adds breath
|
||
# without feeling like a manuscript. Stripe Press / Swift Book
|
||
# / Pragmatic Bookshelf all sit in the 1.08-1.15 range for body.
|
||
linestretch: 1.1
|
||
colorlinks: true
|
||
# Preamble: TinyTorch brand palette + unicode fallback mappings for
|
||
# glyphs outside TeX Gyre's coverage. Brand palette is the canonical
|
||
# source for cover page, fancy headers, chapter titles, listings.
|
||
# Custom cover page split across two files to get around Pandoc's
|
||
# template engine:
|
||
# • title.tex — empty Pandoc partial; suppresses Pandoc's default
|
||
# \title/\author/\date/\maketitle block.
|
||
# • cover.tex — raw LaTeX injected via include-before-body. This
|
||
# path does NOT run the file through Pandoc's
|
||
# template engine, so TikZ coordinates like
|
||
# `($(0,0)+(1cm,1cm)$)` survive intact.
|
||
template-partials:
|
||
- title.tex
|
||
include-before-body:
|
||
- cover.tex
|
||
include-in-header:
|
||
text: |
|
||
% ── Packages required by the cover page (title.tex) ─────────────
|
||
% tikz: asymmetric neural-net border decorations on the titlepage
|
||
% tcolorbox: the soft grey MLSysBook badge box
|
||
% graphicx + hyperref are loaded by Quarto's default preamble.
|
||
\usepackage{tikz}
|
||
\usetikzlibrary{calc,positioning,decorations.pathmorphing}
|
||
% [most] preloads skins/breakable/theorems/... so downstream
|
||
% callouts (Quarto uses tcolorbox for :::{.callout-*}) don't
|
||
% surprise us with missing-library errors.
|
||
\usepackage[most]{tcolorbox}
|
||
|
||
% ── TinyTorch brand palette (parity with legacy jupyter-book PDF) ──
|
||
\definecolor{torchnavy}{RGB}{27,58,95} % headings, internal links
|
||
\definecolor{flameorange}{RGB}{255,130,70} % accents, URLs, code frame
|
||
\definecolor{flamered}{RGB}{210,35,65} % syntax strings
|
||
\definecolor{bodygray}{RGB}{40,40,40} % body text
|
||
\definecolor{codebackground}{RGB}{255,248,240} % peachy code-block fill
|
||
\definecolor{accentwarm}{RGB}{255,160,100} % soft warm accent
|
||
% Legacy placeholder retained in case anything keys off it.
|
||
\definecolor{tinytorch}{HTML}{D4740C}
|
||
|
||
% ── Unicode fallbacks — glyphs TeX Gyre does not cover ──────────
|
||
\usepackage{newunicodechar}
|
||
% Difficulty dots used in module-header tables (●○○○ etc.)
|
||
\newunicodechar{●}{$\bullet$}
|
||
\newunicodechar{○}{$\circ$}
|
||
\newunicodechar{◐}{$\bullet$}
|
||
\newunicodechar{◑}{$\bullet$}
|
||
\newunicodechar{◒}{$\bullet$}
|
||
\newunicodechar{◓}{$\bullet$}
|
||
\newunicodechar{▪}{$\blacksquare$}
|
||
\newunicodechar{▫}{$\square$}
|
||
\newunicodechar{☆}{$\star$}
|
||
\newunicodechar{★}{$\bigstar$}
|
||
% Math / arrow symbols that may appear in narrative prose
|
||
\newunicodechar{→}{$\rightarrow$}
|
||
\newunicodechar{←}{$\leftarrow$}
|
||
\newunicodechar{↔}{$\leftrightarrow$}
|
||
\newunicodechar{⟶}{$\longrightarrow$}
|
||
\newunicodechar{×}{$\times$}
|
||
\newunicodechar{÷}{$\div$}
|
||
\newunicodechar{≈}{$\approx$}
|
||
\newunicodechar{≠}{$\neq$}
|
||
\newunicodechar{≤}{$\leq$}
|
||
\newunicodechar{≥}{$\geq$}
|
||
\newunicodechar{∈}{$\in$}
|
||
\newunicodechar{∞}{$\infty$}
|
||
\newunicodechar{√}{$\sqrt{}$}
|
||
\newunicodechar{∑}{$\sum$}
|
||
\newunicodechar{∏}{$\prod$}
|
||
\newunicodechar{∂}{$\partial$}
|
||
\newunicodechar{∇}{$\nabla$}
|
||
% Greek — occasional math notation in module discussions
|
||
\newunicodechar{α}{$\alpha$}
|
||
\newunicodechar{β}{$\beta$}
|
||
\newunicodechar{γ}{$\gamma$}
|
||
\newunicodechar{δ}{$\delta$}
|
||
\newunicodechar{ε}{$\epsilon$}
|
||
\newunicodechar{θ}{$\theta$}
|
||
\newunicodechar{λ}{$\lambda$}
|
||
\newunicodechar{μ}{$\mu$}
|
||
\newunicodechar{σ}{$\sigma$}
|
||
\newunicodechar{τ}{$\tau$}
|
||
\newunicodechar{φ}{$\phi$}
|
||
\newunicodechar{ω}{$\omega$}
|
||
\newunicodechar{✓}{\checkmark}
|
||
\newunicodechar{✗}{$\times$}
|
||
% Box-drawing — Cursor (monospace) has no box-drawing glyphs
|
||
\newunicodechar{═}{\texttt{=}}
|
||
\newunicodechar{║}{\texttt{|}}
|
||
\newunicodechar{╔}{\texttt{+}}
|
||
\newunicodechar{╗}{\texttt{+}}
|
||
\newunicodechar{╚}{\texttt{+}}
|
||
\newunicodechar{╝}{\texttt{+}}
|
||
|
||
% ── Code-block line wrapping ────────────────────────────────
|
||
% Pandoc emits highlighted code into the `Highlighting` Verbatim
|
||
% environment (from `fancyvrb`). By default that environment does
|
||
% NOT break long lines — they overflow the page right margin and
|
||
% fall off the printable area. fvextra is a drop-in superset of
|
||
% fancyvrb that adds `breaklines`, plus visual cues so a wrapped
|
||
% line is unambiguously a continuation, not a new statement.
|
||
\usepackage{fvextra}
|
||
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{%
|
||
breaklines,%
|
||
breakanywhere,%
|
||
breaksymbolleft={\color{flameorange!60}\hookrightarrow\space},%
|
||
breaksymbolright={},%
|
||
breakanywheresymbolpre={},%
|
||
breakanywheresymbolpost={},%
|
||
commandchars=\\\{\}%
|
||
}
|
||
% Plain ``` fences (no language tag) render through Pandoc's
|
||
% `verbatim` environment. Same treatment so ASCII art / shell
|
||
% snippets without syntax highlighting also wrap cleanly.
|
||
\RecustomVerbatimEnvironment{verbatim}{Verbatim}{%
|
||
breaklines,%
|
||
breakanywhere,%
|
||
breaksymbolleft={\color{flameorange!60}\hookrightarrow\space},%
|
||
breaksymbolright={}%
|
||
}
|
||
|
||
% =============================================================
|
||
% Professional styling — fancy header/footer, chapter format,
|
||
% section hierarchy, microtype polish, widow/orphan discipline,
|
||
% callout palette. Informed by a reference pass over Swift Book /
|
||
% Rust Book / Stripe Press / Hennessy & Patterson layouts.
|
||
% =============================================================
|
||
\usepackage{fancyhdr}
|
||
\usepackage{titlesec}
|
||
|
||
% Global image size cap. Any raw \includegraphics call (whether
|
||
% emitted by Pandoc from markdown `![]()`, a raw HTML <img>, or
|
||
% a Mermaid-rendered PDF) is clamped to a sane page fraction.
|
||
% Images already authored below the cap are untouched because
|
||
% these are "max" keys, not fixed width/height. Stops oversized
|
||
% raster assets (tito.png at 2266×1432 rendering to a full page)
|
||
% without having to add `width=` to every source figure.
|
||
\usepackage[export]{adjustbox}
|
||
\let\TTOrigIncludeGraphics\includegraphics
|
||
% Cap keys AFTER the user's own options so adjustbox re-evaluates
|
||
% width/height against the max- bounds. With `max width` listed
|
||
% first (before #1), an explicit `width=9.53in` from Pandoc wins
|
||
% and the cap never fires. Placed last, the max- keys clamp any
|
||
% over-wide Pandoc-emitted mermaid PNG to the textblock.
|
||
\renewcommand{\includegraphics}[2][]{%
|
||
\TTOrigIncludeGraphics[%
|
||
keepaspectratio,#1,%
|
||
max width=0.75\linewidth,%
|
||
max height=0.45\textheight%
|
||
]{#2}%
|
||
}
|
||
% microtype is already loaded by Quarto's default template;
|
||
% tune it here rather than re-loading. On XeLaTeX only
|
||
% PROTRUSION and TRACKING are available — font expansion
|
||
% (stretch/shrink/factor) is a pdfLaTeX/LuaLaTeX feature and
|
||
% raises a hard error if enabled. Protrusion alone still
|
||
% gives us ~80% of microtype's visible improvement.
|
||
\microtypesetup{%
|
||
activate={true,nocompatibility},%
|
||
final,%
|
||
tracking=true,%
|
||
protrusion=true,%
|
||
expansion=false%
|
||
}
|
||
|
||
% ── Page-break hygiene ─────────────────────────────────────
|
||
% Prevent single-line widows/orphans at page boundaries.
|
||
\widowpenalty=10000
|
||
\clubpenalty=10000
|
||
% Ragged bottom so widow/orphan control doesn't stretch
|
||
% internal vertical whitespace to justify page height.
|
||
\raggedbottom
|
||
|
||
% ── Headers & footers ──────────────────────────────────────
|
||
% Running head composition:
|
||
% - VERSO (even page): chapter name on outer-left in small
|
||
% caps navy!60. Wordmark centered. Page number outer-left
|
||
% in footer.
|
||
% - RECTO (odd page): section name on outer-right in small
|
||
% caps navy!60. Wordmark centered. Page number outer-right
|
||
% in footer.
|
||
% This is the H&P / CLRS / Swift-Book convention: readers
|
||
% always know their chapter (by looking left) and their section
|
||
% (by looking right) without flipping to the TOC.
|
||
%
|
||
% Mark commands: \chaptermark sets \leftmark (used on verso);
|
||
% \sectionmark sets \rightmark (used on recto). Both use small
|
||
% caps for that editorial textbook feel.
|
||
\setlength{\headheight}{18pt}
|
||
\setlength{\headsep}{16pt}
|
||
\renewcommand{\chaptermark}[1]{\markboth{Chapter \thechapter\ · #1}{}}
|
||
\renewcommand{\sectionmark}[1]{\markright{\thesection\ · #1}}
|
||
\fancypagestyle{tinytorch}{%
|
||
\fancyhf{}%
|
||
\fancyhead[LE]{\footnotesize\color{torchnavy!60}\scshape\nouppercase{\leftmark}}%
|
||
\fancyhead[RO]{\footnotesize\color{torchnavy!60}\scshape\nouppercase{\rightmark}}%
|
||
\fancyhead[C]{%
|
||
\footnotesize\color{flameorange}Tiny%
|
||
\kern1pt\raisebox{-1pt}{%
|
||
\includegraphics[height=9pt]%
|
||
{../assets/images/logos/fire-emoji.png}%
|
||
}%
|
||
\kern1pt\color{torchnavy}Torch%
|
||
}%
|
||
\fancyfoot[LE,RO]{\small\color{torchnavy!60}\thepage}%
|
||
\renewcommand{\headrulewidth}{0pt}%
|
||
\renewcommand{\footrulewidth}{0pt}%
|
||
\renewcommand{\headrule}{%
|
||
\vbox to 0pt{%
|
||
\vskip 3pt%
|
||
{\color{flameorange!70}\hrule height 0.4pt}%
|
||
}%
|
||
}%
|
||
}
|
||
\pagestyle{tinytorch}
|
||
% Chapter-opening pages default to "plain" in the book class.
|
||
% Keep the wordmark + double rule, but drop the chapter/section
|
||
% marks (they'd be redundant — the huge chapter title IS below).
|
||
% Only the page number appears in the footer.
|
||
\fancypagestyle{plain}{%
|
||
\fancyhf{}%
|
||
\fancyhead[C]{%
|
||
\footnotesize\color{flameorange}Tiny%
|
||
\kern1pt\raisebox{-1pt}{%
|
||
\includegraphics[height=9pt]%
|
||
{../assets/images/logos/fire-emoji.png}%
|
||
}%
|
||
\kern1pt\color{torchnavy}Torch%
|
||
}%
|
||
\fancyfoot[LE,RO]{\small\color{torchnavy!60}\thepage}%
|
||
\renewcommand{\headrulewidth}{0pt}%
|
||
\renewcommand{\footrulewidth}{0pt}%
|
||
\renewcommand{\headrule}{%
|
||
\vbox to 0pt{%
|
||
\vskip 3pt%
|
||
{\color{flameorange!70}\hrule height 0.4pt}%
|
||
}%
|
||
}%
|
||
}
|
||
|
||
% ── Chapter styling ────────────────────────────────────────
|
||
% Flame-emoji icon + "Chapter N" in flameorange as an eyebrow,
|
||
% Huge torchnavy bold title beneath, hairline navy!30 rule to
|
||
% close the block. Matches the legacy jupyter-book layout.
|
||
\titleformat{\chapter}[display]
|
||
{\normalfont\sffamily}
|
||
{\color{flameorange}\Large\bfseries
|
||
\raisebox{-2pt}{%
|
||
\includegraphics[height=1em]%
|
||
{../assets/images/logos/fire-emoji.png}%
|
||
}\,Chapter \thechapter}
|
||
{0.6em}
|
||
{\color{torchnavy}\Huge\bfseries}
|
||
[\vspace{0.5em}%
|
||
{\color{torchnavy!30}\titlerule[0.4pt]}]
|
||
\titlespacing*{\chapter}{0pt}{10pt}{28pt}
|
||
% Running head carries just the chapter title (no number).
|
||
\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
|
||
|
||
% ── Part page styling ──────────────────────────────────────
|
||
% Default `book` class renders Part pages as plain serif black
|
||
% "Part I" / "Foundation Tier" stacked centered. Repaint with
|
||
% the brand palette so Part dividers carry the same identity as
|
||
% chapter openers: flameorange "PART I" eyebrow, torchnavy
|
||
% bold sans title, hairline rule above and below to give the
|
||
% page weight without any color blocking.
|
||
\titleformat{\part}[display]
|
||
{\centering\normalfont\sffamily}
|
||
{\vspace*{0.15\textheight}%
|
||
{\color{flameorange!50}\titlerule[0.6pt]}\vspace{1em}%
|
||
{\color{flameorange}\large\bfseries\MakeUppercase{\partname~\thepart}}}
|
||
{0.8em}
|
||
{\color{torchnavy}\Huge\bfseries}
|
||
[\vspace{1em}{\color{flameorange!50}\titlerule[0.6pt]}]
|
||
\titlespacing*{\part}{0pt}{0pt}{0pt}
|
||
|
||
% ── Section hierarchy ──────────────────────────────────────
|
||
% Sans-serif navy titles, flameorange numerals. Weight and
|
||
% color fade as level depth increases so the reader's eye
|
||
% can instantly tell section from subsection from subsub.
|
||
% Section numeral is deliberately \mdseries (medium weight) so
|
||
% it visually recedes next to the bold title word — keeps the
|
||
% heading readable as "Overview" with "5.1" as a calm anchor,
|
||
% not two equally-loud elements fighting for attention.
|
||
\titleformat{\section}
|
||
{\normalfont\sffamily\Large\bfseries\color{torchnavy}}
|
||
{\color{flameorange}\mdseries\thesection}{0.75em}{}
|
||
\titleformat{\subsection}
|
||
{\normalfont\sffamily\large\bfseries\color{torchnavy!85}}
|
||
{\color{torchnavy!60}\thesubsection}{0.6em}{}
|
||
\titleformat{\subsubsection}
|
||
{\normalfont\sffamily\normalsize\bfseries\color{torchnavy!75}}
|
||
{}{0em}{}
|
||
\titlespacing*{\section}{0pt}{1.4em}{0.6em}
|
||
\titlespacing*{\subsection}{0pt}{1.1em}{0.4em}
|
||
\titlespacing*{\subsubsection}{0pt}{0.9em}{0.3em}
|
||
|
||
% ── Book-style paragraph typography ────────────────────────
|
||
% Classic print convention: first-line indent marks paragraph
|
||
% starts (not blank-line gaps). 1.2em indent reads well at
|
||
% Palatino's x-height. LaTeX's default is to NOT indent the
|
||
% first paragraph after a heading (correct book convention);
|
||
% we don't override that. parskip set tight so the visual
|
||
% paragraph rhythm comes from the indent, not from whitespace.
|
||
%
|
||
% Exception: inside callouts, lists, code, and table cells,
|
||
% first-line indent is visually wrong — disable there via the
|
||
% \@afterindentfalse hooks that Quarto's default template
|
||
% already sets.
|
||
\setlength{\parskip}{0pt plus 0.5pt}
|
||
\setlength{\parindent}{1.2em}
|
||
|
||
% ── Callout title conventions ──────────────────────────────
|
||
% Quarto ships 5 callout classes (note, tip, warning, caution,
|
||
% important). For a lab book we want 6+ semantic types. We
|
||
% achieve this via CLASS + TITLE-WORD conventions — NOT emoji
|
||
% prefixes — because strip-emojis.lua removes all U+1F300-1FAFF
|
||
% and U+2600-27FF codepoints during PDF render (XeLaTeX's
|
||
% Latin Modern fonts don't cover emoji glyphs cross-platform).
|
||
%
|
||
% Semantic → Quarto class + title pattern:
|
||
%
|
||
% Check Your Understanding → callout-tip title="Check Your Understanding — <Module>"
|
||
% Systems Implication → callout-note title="Systems Implication: <Topic>"
|
||
% Historical Context → callout-note title="Historical Context"
|
||
% Exercise → callout-note title="Exercise"
|
||
% Pitfall → callout-warning title="Pitfall: <Topic>"
|
||
% Checkpoint → callout-important title="Checkpoint"
|
||
%
|
||
% The class drives the colored left-bar (tip=green, note=blue,
|
||
% warning=orange, important=red) which is sufficient semantic
|
||
% signal without emoji. Titles are text-only; survive strip
|
||
% filter; render identically on macOS and Ubuntu CI.
|
||
|
||
% ── Table row spacing ──────────────────────────────────────
|
||
% Default \arraystretch is 1.0 which packs table rows tightly.
|
||
% 1.2 gives tables ~20% more vertical breathing room — matches
|
||
% the Swift Book / Stripe Press table density. Global, applies
|
||
% to every \begin{tabular} Pandoc emits from pipe/grid tables.
|
||
\renewcommand{\arraystretch}{1.2}
|
||
|
||
% ── List item spacing ──────────────────────────────────────
|
||
% Quarto's default lists use LaTeX's stock itemsep which reads
|
||
% cramped at body font size. Small bump via enumitem gives
|
||
% numbered and bulleted lists the same air as paragraph breaks
|
||
% without making them feel loose.
|
||
\usepackage{enumitem}
|
||
\setlist[enumerate]{itemsep=0.3em,topsep=0.3em}
|
||
\setlist[itemize]{itemsep=0.3em,topsep=0.3em}
|
||
|
||
% ── Callout palette ────────────────────────────────────────
|
||
% Quarto's :::{.callout-*} directives emit tcolorboxes keyed
|
||
% off named colors. Redefining those names repaints all
|
||
% callouts without having to override the tcolorbox wrapper
|
||
% itself. Frame + fill use the same hue family; fill is a
|
||
% light tint of the frame so boxes feel integrated, not boxed.
|
||
\definecolor{quarto-callout-note-color}{RGB}{27,58,95}
|
||
\definecolor{quarto-callout-tip-color}{RGB}{45,122,61}
|
||
\definecolor{quarto-callout-warning-color}{RGB}{255,130,70}
|
||
\definecolor{quarto-callout-caution-color}{RGB}{210,35,65}
|
||
\definecolor{quarto-callout-important-color}{RGB}{196,82,96}
|
||
\definecolor{quarto-callout-note-color-frame}{RGB}{27,58,95}
|
||
\definecolor{quarto-callout-tip-color-frame}{RGB}{45,122,61}
|
||
\definecolor{quarto-callout-warning-color-frame}{RGB}{255,130,70}
|
||
\definecolor{quarto-callout-caution-color-frame}{RGB}{210,35,65}
|
||
\definecolor{quarto-callout-important-color-frame}{RGB}{196,82,96}
|
||
|
||
% Callout title typography: bold sans in torchnavy, with a bit
|
||
% more air above/below each box. Applies globally to every
|
||
% Quarto callout (note/tip/warning/caution/important) because
|
||
% Quarto wraps them all in a tcolorbox — one \tcbset beats
|
||
% five per-class overrides.
|
||
\tcbset{%
|
||
fonttitle=\bfseries\sffamily\color{torchnavy},%
|
||
beforeafter skip=6pt%
|
||
}
|
||
# Semantic link coloring matching legacy PDF: internal cross-refs and
|
||
# citations read as navy (calm, textural); external URLs pop in
|
||
# flameorange so they stand out as "this leaves the book".
|
||
linkcolor: torchnavy
|
||
urlcolor: flameorange
|
||
citecolor: torchnavy
|
||
# Raw ```{=html}``` blocks are automatically skipped in PDF output
|
||
# (Pandoc only emits raw-html into html targets). Action cards,
|
||
# PDF viewers, and interactive widgets drop out cleanly.
|
||
fig-pos: "H"
|
||
# Center every figure in the page column. The \includegraphics override
|
||
# above caps images at 0.75\linewidth, so without explicit centering
|
||
# they hug the left margin with ~25% of the column blank to the right.
|
||
# `fig-align: center` makes Pandoc wrap each image in \centering inside
|
||
# its figure environment.
|
||
fig-align: center
|
||
code-line-numbers: false
|
||
# Code-block styling. Quarto wraps fenced code in a tcolorbox whose
|
||
# colors it picks up from these YAML keys — peachy `codebackground`
|
||
# fill with a flameorange left border matches the legacy
|
||
# listings style (Stripe Press-adjacent premium feel) without
|
||
# needing a raw \lstset block, which Quarto would ignore anyway.
|
||
code-block-bg: "#fff8f0"
|
||
code-block-border-left: "#ff8246"
|
||
# Use `tango` for token coloring; it sits comfortably against the
|
||
# peachy background and keeps string literals in warm tones so the
|
||
# overall code look stays in the TinyTorch palette family.
|
||
highlight-style: tango
|
||
|
||
execute:
|
||
enabled: false
|
||
|
||
# Pandoc Lua filters.
|
||
# strip-emojis.lua — drops emoji codepoints when rendering to LaTeX.
|
||
# XeLaTeX's default Latin Modern font doesn't cover emoji ranges
|
||
# and there is no emoji font available cross-platform (macOS vs CI
|
||
# Ubuntu), so we strip them for the PDF target. HTML rendering is
|
||
# unaffected.
|
||
# ../tools/diagrams/svg-to-pdf.lua — rewrites
|
||
# `assets/images/diagrams/*.svg` to the matching `.pdf` produced by
|
||
# `make figures` (rsvg-convert) so the LaTeX build embeds our
|
||
# pre-converted vector PDFs instead of having Quarto run its own
|
||
# SVG→PDF conversion implicitly. See the Makefile in the parent
|
||
# directory for the full pipeline.
|
||
filters:
|
||
- strip-emojis.lua
|
||
- ../tools/diagrams/svg-to-pdf.lua
|