Skip to content

Commit 8a9e78e

Browse files
cdervcderv
authored
Merge pull request #13249 from quarto-dev/deps/pandoc-2025-08
[deps] Pandoc 3.8.3, typst 0.14.2
2 parents c99ac47 + 980761c commit 8a9e78e

File tree

87 files changed

+1881
-256
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+1881
-256
lines changed

‎configuration‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,16 @@
77
# but it also used when packaging (e.g. run configure.sh, then prepare-dist.sh, then package.sh)
88
# deno_dom should match release at https://github.com/b-fuze/deno-dom/releases
99

10-
# NB: When these are updated, you must also update the versions
10+
# IMPORTANT: When these are updated, you must also update the versions
1111
# in src/command/check/check.ts
12-
1312
# Binary dependencies
1413
export DENO=v2.4.5
1514
# TODO figure out where 0.1.41 apple silicon libs are available
1615
export DENO_DOM=v0.1.41-alpha-artifacts
17-
export PANDOC=3.6.3
16+
export PANDOC=3.8.3
1817
export DARTSASS=1.87.0
1918
export ESBUILD=0.25.10
20-
export TYPST=0.13.0
19+
export TYPST=0.14.2
2120

2221

2322
# NB: we can't put comments in the same line as export statements because it

‎dev-docs/feature-format-matrix/qmd-files/math/document.qmd‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ format:
55
html: default
66
_quarto:
77
tests:
8+
run:
9+
skip: "Pandoc 3.7+ removes newlines in display math blocks (fixed in pandoc@8123be6, awaiting release)"
810
html:
911
ensureHtmlElements:
1012
- []

‎dev-docs/update-pandoc-checklist.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,25 @@ Carlos needs to run this:
66
- [ ] Run `AWS_PROFILE=... ./package/src/quarto-bld update-pandoc PANDOC_VERSION`
77
- [ ] look at `git diff`, specifically for changes in Pandoc templates, and adjust as needed.
88

9+
As a reminder, our templates are kept in the same directories as Pandoc's templates, but with different names. `git diff` will show the diff in Pandoc's template; we have to manually patch
10+
ours. (We can't just use `patch` because the templates have diverged too much)
11+
12+
### Pandoc templates
13+
14+
The general rule for the naming is that "format.template" indicates Pandoc naming, and "template.format" indicates ours. Examples below:
15+
16+
#### beamer
17+
18+
- Pandoc's: src/resources/formats/beamer/pandoc/beamer.template
19+
- Ours: src/resources/formats/beamer/pandoc/template.tex
20+
21+
Partials:
22+
23+
- Pandoc's:
24+
- src/resources/formats/beamer/pandoc/latex.common
25+
- Ours:
26+
- src/resources/formats/beamer/pandoc/common.latex
27+
928
## Manual steps
1029

1130
- [ ] Update schemas by inspecting [their changelog](https://github.com/jgm/pandoc/blob/main/changelog.md) for new commands, deprecation removals, etc

‎llm-docs/pandoc-quarto-latex-templates.md‎

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
# Pandoc and Quarto LaTeX Templates
2+
3+
This document describes how Quarto integrates Pandoc's LaTeX templates and transforms them into a modular structure suitable for Quarto's extended functionality.
4+
5+
## 1. How Pandoc Templates Are Copied into Quarto
6+
7+
The `writePandocTemplates` function in `package/src/common/update-pandoc.ts` handles copying Pandoc's templates into Quarto's resources during the Pandoc update process.
8+
9+
### Source and Destination
10+
11+
- **Source**: Pandoc templates are downloaded from the Pandoc GitHub repository's `data/templates/` directory
12+
- **Destination**: `src/resources/formats/pdf/pandoc/`
13+
14+
### Files Copied
15+
16+
Seven files are copied from Pandoc for LaTeX support:
17+
18+
| Pandoc Source | Quarto Destination | Notes |
19+
| ----------------------------- | ------------------ | -------------------------------------------------- |
20+
| `default.latex` | `latex.template` | Main Pandoc template |
21+
| `common.latex` | `latex.common` | Reference copy (Quarto maintains modified version) |
22+
| `after-header-includes.latex` | (unchanged) | Post-header-includes processing |
23+
| `hypersetup.latex` | (unchanged) | Hyperref configuration |
24+
| `font-settings.latex` | (unchanged) | User font configuration |
25+
| `fonts.latex` | (unchanged) | Font engine detection |
26+
| `passoptions.latex` | (unchanged) | Package options passthrough |
27+
28+
### Purpose of Each Pandoc File
29+
30+
**default.latex** (becomes `latex.template`): The main Pandoc LaTeX template. Quarto uses its own `template.tex` as the main orchestrator instead.
31+
32+
**common.latex** (becomes `latex.common`): Common preamble setup from Pandoc including paragraph formatting, verbatim settings, highlighting, tables, graphics, citations, and bibliography. Quarto keeps this as a reference copy.
33+
34+
**after-header-includes.latex**: Processing after user-provided header includes. Sets up xspace, bookmark, and URL packages.
35+
36+
**hypersetup.latex**: Hyperref configuration for PDF links, colors, and metadata.
37+
38+
**font-settings.latex**: User font configuration for different TeX engines (PDFTeX, XeTeX, LuaTeX). Handles mainfont, sansfont, monofont, mathfont, and CJK fonts.
39+
40+
**fonts.latex**: Font engine detection and setup. Loads fontspec for XeTeX/LuaTeX, handles font fallbacks.
41+
42+
**passoptions.latex**: Package options passthrough mechanism for hyperref, xcolor, and xeCJK.
43+
44+
## 2. Quarto's Modular Template Structure
45+
46+
Quarto breaks the Pandoc templates into a modular structure in `src/resources/formats/pdf/pandoc/`. This allows for:
47+
48+
- Better separation of concerns
49+
- Easier customization and extension
50+
- Support for Quarto-specific features (author normalization, bibliography control)
51+
52+
### File Extension Convention
53+
54+
Quarto uses file extensions to distinguish template origin:
55+
56+
- `.tex` files: Quarto-maintained partials
57+
- `.latex` files: Pandoc-derived partials
58+
59+
### Template Files
60+
61+
The `pdfFormat` function in `src/format/pdf/format-pdf.ts` configures the template context, specifying `template.tex` as the main template with partials from both Quarto (`.tex`) and Pandoc (`.latex`).
62+
63+
### template.tex - The Orchestrator
64+
65+
Assembles the document by including all partials in order. This is Quarto's main template, distinct from Pandoc's `latex.template`.
66+
67+
### The "common" Files Architecture
68+
69+
Quarto maintains two versions of the common preamble:
70+
71+
**latex.common** (264 lines): Pandoc's original, kept as reference. Contains the full common preamble: paragraph formatting, verbatim, highlighting, tables, graphics, strikeout, CSL citations, Babel, page style, tight lists, subfigure support, text direction, natbib/biblatex configuration.
72+
73+
**common.latex** (66 lines): Quarto's shortened version that:
74+
75+
- Keeps Pandoc's paragraph formatting, verbatim, and listings setup
76+
- Calls `$pandoc.tex()$` to delegate the rest to Quarto partials
77+
78+
This allows Quarto to selectively override specific parts of the common preamble while maintaining compatibility with Pandoc updates.
79+
80+
### Quarto Partials (\*.tex)
81+
82+
**Document Structure:**
83+
84+
| File | Purpose |
85+
| ------------------ | -------------------------------------------------------------------------------------------------- |
86+
| `doc-class.tex` | Document class declaration with babel languages, fontsize, papersize, and class options |
87+
| `before-title.tex` | Empty placeholder for pre-title content |
88+
| `title.tex` | Title, subtitle, author, and date setup. Uses Quarto's `authors` normalization (`it.name.literal`) |
89+
| `before-body.tex` | Frontmatter, `\maketitle`, and abstract rendering |
90+
| `toc.tex` | Table of contents, list of figures, list of tables |
91+
| `after-body.tex` | Empty placeholder for post-body content |
92+
93+
**Bibliography:**
94+
95+
| File | Purpose |
96+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
97+
| `before-bib.tex` | Empty placeholder before bibliography |
98+
| `biblio.tex` | Bibliography rendering with natbib or biblatex |
99+
| `biblio-config.tex` | Bibliography package configuration. Adds `$biblio-config$` conditional (Quarto-only variable) to allow class files to handle bibliography configuration |
100+
101+
**Content Elements (called via pandoc.tex):**
102+
103+
| File | Purpose |
104+
| ---------------- | --------------------------------------------------------------------------- |
105+
| `tables.tex` | Table packages (longtable, booktabs, array, multirow) and footnote handling |
106+
| `graphics.tex` | graphicx package and `\pandocbounded` command for auto-scaling images |
107+
| `citations.tex` | CSL citation definitions (`\citeproc`, `CSLReferences` environment) |
108+
| `babel-lang.tex` | Babel language configuration and font setup |
109+
| `tightlist.tex` | `\tightlist` command for compact list spacing |
110+
111+
**Hub Partial:**
112+
113+
| File | Purpose |
114+
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115+
| `pandoc.tex` | Hub that calls other Quarto partials. Contains highlighting, strikeout/underline, page style, subfigure support, text direction. Calls: `$tables.tex()$`, `$graphics.tex()$`, `$citations.tex()$`, `$babel-lang.tex()$`, `$tightlist.tex()$`, `$biblio-config.tex()$` |
116+
117+
## 3. Template Invocation Order
118+
119+
The `template.tex` orchestrates the full document:
120+
121+
### Preamble (before `\begin{document}`)
122+
123+
1. `$passoptions.latex()$` - Package options passthrough
124+
2. `$doc-class.tex()$` - `\documentclass[...]{...}` declaration
125+
3. (inline) - beamerarticle, xcolor, geometry, amsmath
126+
4. (inline) - Section numbering configuration
127+
5. `$fonts.latex()$` - Font engine detection (ifPDFTeX, ifXeTeX, ifLuaTeX)
128+
6. `$font-settings.latex()$` - User font configuration
129+
7. `$common.latex()$` - Common preamble setup, which internally calls:
130+
- `$pandoc.tex()$` → `$tables.tex()$`, `$graphics.tex()$`, `$citations.tex()$`, `$babel-lang.tex()$`, `$tightlist.tex()$`, `$biblio-config.tex()$`
131+
8. `$after-header-includes.latex()$` - Bookmark, URL packages
132+
9. `$hypersetup.latex()$` - Hyperref configuration
133+
10. `$before-title.tex()$` - Pre-title content
134+
11. `$title.tex()$` - `\title{}`, `\author{}`, `\date{}`
135+
136+
### Document Body
137+
138+
12. `\begin{document}`
139+
13. `$before-body.tex()$` - Frontmatter, `\maketitle`, abstract
140+
14. (loop) - include-before content
141+
15. `$toc.tex()$` - Table of contents
142+
16. (inline) - linestretch, mainmatter
143+
17. `$body$` - Document content
144+
18. `$before-bib.tex()$` - Pre-bibliography content
145+
19. (inline) - backmatter, nocite
146+
20. `$biblio.tex()$` - Bibliography rendering
147+
21. (loop) - include-after content
148+
22. `$after-body.tex()$` - Post-body content
149+
23. `\end{document}`
150+
151+
## 4. TypeScript Configuration
152+
153+
The `pdfFormat` function in `src/format/pdf/format-pdf.ts` (lines 236-284) defines the template configuration:
154+
155+
```typescript
156+
// Quarto-maintained partials (.tex)
157+
const partialNamesQuarto: string[] = [
158+
"babel-lang",
159+
"before-bib",
160+
"biblio",
161+
"biblio-config",
162+
"citations",
163+
"doc-class",
164+
"graphics",
165+
"after-body",
166+
"before-body",
167+
"pandoc",
168+
"tables",
169+
"tightlist",
170+
"before-title",
171+
"title",
172+
"toc",
173+
];
174+
175+
// Pandoc-derived partials (.latex)
176+
const partialNamesPandoc: string[] = [
177+
"after-header-includes",
178+
"common",
179+
"font-settings",
180+
"fonts",
181+
"hypersetup",
182+
"passoptions",
183+
];
184+
```
185+
186+
The template context maps these to files:
187+
188+
- Quarto partials: `pandoc/${name}.tex`
189+
- Pandoc partials: `pandoc/${name}.latex`
190+
191+
## 5. Parameter Summary Table
192+
193+
### Font Parameters (XeTeX/LuaTeX)
194+
195+
| Parameter | Type | Description |
196+
| ------------------ | ------ | ---------------------------- |
197+
| `mainfont` | string | Main text font family |
198+
| `mainfontoptions` | array | Font options for main font |
199+
| `mainfontfallback` | array | Fallback fonts for main font |
200+
| `sansfont` | string | Sans-serif font family |
201+
| `sansfontoptions` | array | Font options for sans font |
202+
| `sansfontfallback` | array | Fallback fonts for sans font |
203+
| `monofont` | string | Monospace font family |
204+
| `monofontoptions` | array | Font options for mono font |
205+
| `monofontfallback` | array | Fallback fonts for mono font |
206+
| `mathfont` | string | Math font family |
207+
| `mathfontoptions` | array | Font options for math font |
208+
209+
### Font Parameters (PDFTeX)
210+
211+
| Parameter | Type | Description |
212+
| ------------------- | ------ | -------------------------------------- |
213+
| `fontfamily` | string | Font package name (e.g., "libertinus") |
214+
| `fontfamilyoptions` | array | Options for font package |
215+
| `fontenc` | string | Font encoding (default: "T1") |
216+
217+
### CJK Font Parameters
218+
219+
| Parameter | Type | Description |
220+
| ------------- | ------ | ---------------- |
221+
| `CJKmainfont` | string | CJK main font |
222+
| `CJKsansfont` | string | CJK sans font |
223+
| `CJKmonofont` | string | CJK mono font |
224+
| `CJKoptions` | array | CJK font options |
225+
226+
### Layout Parameters
227+
228+
| Parameter | Type | Description |
229+
| --------------- | ------ | ----------------------------------------------- |
230+
| `documentclass` | string | Document class (default: "scrartcl" for Quarto) |
231+
| `classoption` | array | Class options (e.g., "12pt", "twoside") |
232+
| `papersize` | string | Paper size (e.g., "letter", "a4") |
233+
| `geometry` | array | Geometry package options |
234+
| `linestretch` | number | Line spacing multiplier |
235+
236+
### Section Parameters
237+
238+
| Parameter | Type | Description |
239+
| ---------------- | ------- | ----------------------------- |
240+
| `numbersections` | boolean | Enable section numbering |
241+
| `secnumdepth` | integer | Depth of section numbering |
242+
| `fontsize` | string | Base font size (e.g., "11pt") |
243+
244+
### Color Parameters
245+
246+
| Parameter | Type | Description |
247+
| ----------- | ------ | ------------------------ |
248+
| `linkcolor` | string | Color for internal links |
249+
| `citecolor` | string | Color for citations |
250+
| `urlcolor` | string | Color for URLs |
251+
| `toccolor` | string | Color for TOC links |
252+
253+
### Bibliography Parameters
254+
255+
| Parameter | Type | Description |
256+
| --------------- | ------- | --------------------------------------------------------------- |
257+
| `natbib` | boolean | Use natbib for citations |
258+
| `biblatex` | boolean | Use biblatex for citations |
259+
| `biblio-style` | string | Bibliography style |
260+
| `biblio-title` | string | Bibliography section title |
261+
| `bibliography` | array | Bibliography file paths |
262+
| `biblio-config` | boolean | Emit bibliography configuration (Quarto-only, defaults to true) |
263+
264+
### Quarto-Specific Parameters
265+
266+
| Parameter | Quarto Name | Description |
267+
| ------------------------ | ------------------------ | ----------------------------------------------------- |
268+
| `number-sections` | `numbersections` | Enable section numbering |
269+
| `shift-heading-level-by` | `shift-heading-level-by` | Auto-set to -1 when numbersections and no L1 headings |
270+
| `toc` | `toc` | Include table of contents |
271+
| `toc-depth` | `toc-depth` | TOC depth |
272+
| `toc-title` | `toc-title` | TOC heading |
273+
| `lof` | `lof` | Include list of figures |
274+
| `lot` | `lot` | Include list of tables |
275+
276+
### Brand.yaml Integration
277+
278+
**Important**: Unlike HTML and Typst formats, LaTeX does NOT have automatic brand.yaml fallback for typography. Font and color settings must be specified explicitly via Pandoc metadata variables:
279+
280+
```yaml
281+
format:
282+
pdf:
283+
mainfont: "Inter"
284+
sansfont: "Outfit"
285+
monofont: "Fira Code"
286+
fontsize: 11pt
287+
```

0 commit comments

Comments
 (0)