Skip to content

Commit c3e0f5c

Browse files
committed
Revert premature merge of update-pandoc-3.10.1 branch
Branch was pushed directly to main before it was ready. Reverts: d7e1e82 429716b 7d6becd 74bf7cd 443f7a3 4904002 49b08b3 bd2f023 9d9291d 9390162 65ee316 1321360 6234511 The corresponding work continues on the update-pandoc-3.10.1 branch, unaffected by this revert.
1 parent d7e1e82 commit c3e0f5c

19 files changed

Lines changed: 90 additions & 379 deletions

File tree

‎.claude/rules/dev-tools/dependency-updates.md‎

Lines changed: 0 additions & 10 deletions
This file was deleted.
Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,12 @@
11
---
22
paths:
33
- "src/resources/formats/pdf/pandoc/**"
4-
- "src/resources/formats/beamer/pandoc/**"
54
- "src/resources/formats/typst/pandoc/**"
6-
- "src/resources/formats/html/pandoc/**"
7-
- "src/resources/formats/revealjs/pandoc/**"
8-
- "src/resources/formats/asciidoc/pandoc/**"
95
- "package/src/common/update-pandoc.ts"
10-
- "dev-docs/update-pandoc-checklist.md"
116
---
127

13-
# Pandoc Templates (LaTeX, Typst, HTML, Reveal.js, AsciiDoc)
8+
# Pandoc Templates (LaTeX & Typst)
149

1510
For how Pandoc's LaTeX templates are copied into Quarto and restructured into a modular form (`latex.template`, `latex.common`, …), see `llm-docs/pandoc-quarto-latex-templates.md`.
1611

1712
For the equivalent Typst template integration (`typst.template`, `template.typst`), see `llm-docs/pandoc-quarto-typst-templates.md`.
18-
19-
Every format's `pandoc/` directory has the same split: a dev-reference-only copy of Pandoc's own template (unreferenced by any TypeScript code — kept only so a maintainer can diff it against a fresh Pandoc checkout) alongside Quarto's actual, wired-up template. `dev-docs/update-pandoc-checklist.md` has the full per-format file list (pdf, beamer, html, revealjs, asciidoc, typst) and the naming gotcha that makes the reference-copy file easy to miss when checking what's in a directory.

‎.github/actions/README.md‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎.github/workflows/actions/README.md‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎.github/workflows/actions/pandoc-override/action.yml‎

Lines changed: 0 additions & 38 deletions
This file was deleted.

‎.github/workflows/test-smokes.yml‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,6 @@ on:
3535
required: false
3636
type: string
3737
default: ""
38-
pandoc-override-version:
39-
description: "Pandoc release tag to download from GitHub and use via QUARTO_PANDOC instead of the archived/configured version (e.g. 3.10.1) - for smoke-testing a version before it has been archived to S3. Leave empty for normal behavior."
40-
required: false
41-
type: string
42-
default: ""
4338
schedule:
4439
- cron: "0 6 * * *"
4540

@@ -234,10 +229,6 @@ jobs:
234229
235230
- uses: ./.github/workflows/actions/quarto-dev
236231

237-
- uses: ./.github/workflows/actions/pandoc-override
238-
with:
239-
pandoc-version: ${{ inputs.pandoc-override-version }}
240-
241232
- name: Install Tinytex
242233
env:
243234
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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

Lines changed: 6 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,13 @@
11
## Updating the bundled version of Pandoc
22

3-
Updating Pandoc happens in two phases. Phase 1 (prep) needs no S3 access and can be done by anyone; Phase 2 (archival) is done by whoever holds S3 write credentials, right before merge.
3+
Carlos needs to run this:
44

5-
### Phase 1 - prep (no S3, anyone)
5+
- [ ] Ensure archives are upgraded
6+
- [ ] Run `AWS_PROFILE=... ./package/src/quarto-bld update-pandoc PANDOC_VERSION`
7+
- [ ] look at `git diff`, specifically for changes in Pandoc templates, and adjust as needed.
68

7-
Patch Quarto's wired-up template files and regenerate the dev-reference copies + `src/core/pandoc/format-extension.ts`, then verify rendering - all while `configuration`'s `export PANDOC=` line stays pinned at the currently-archived version, so plain `./configure.sh`/`.cmd` keeps working for everyone else.
8-
9-
Run the template/variant regeneration with `--skip-archive`, pointing `QUARTO_PANDOC` at a real binary of the target version:
10-
11-
```bash
12-
QUARTO_PANDOC=/path/to/pandoc-3.10.1/bin/pandoc \
13-
./package/src/quarto-bld update-pandoc 3.10.1 --skip-archive
14-
```
15-
16-
`--skip-archive` skips the S3 archival, the `configureDependency` download, and the `configuration` rewrite. It still runs `writePandocTemplates` (regenerates every mapped template + dev-reference copy) and `writeVariants` (regenerates `format-extension.ts`). `QUARTO_PANDOC` is **required** with `--skip-archive`: `writeVariants` shells out to that binary to enumerate formats/extensions, and without the override it would silently regenerate `format-extension.ts` from the old configured Pandoc. The command leaves everything as an uncommitted working-tree diff for you to review and commit yourself; it never commits.
17-
18-
Running `update-pandoc ... --skip-archive` is itself a safety-net checkpoint: if it produces a diff on a template or dev-reference file that Phase 1 was supposed to have already hand-patched, Phase 1 missed that file - exactly the naming trap described below (this bit twice in one session, on `latex.common` and on the real `styles.html`). A diff limited to `format-extension.ts` is a normal generated change to review, not a miss. The same checkpoint applies to the full Phase 2 run.
19-
20-
Rendering changes can also be smoke-tested before archival: dispatch `.github/workflows/test-smokes.yml` with the `pandoc-override-version` input set to the new release tag (e.g. `3.10.1`). It downloads that Pandoc release directly from GitHub, points `quarto` at it via `QUARTO_PANDOC` for that run only, and leaves the archived/configured version untouched - no S3 access needed. Scope `buckets` to the relevant smoke-all dirs (e.g. `typst`, `latex`, `table`) for a faster signal.
21-
22-
### Phase 2 - archival (S3 credential holder, before merge)
23-
24-
Whoever holds S3 write credentials does this last, right before merging:
25-
26-
- [ ] Bump `configuration`'s `export PANDOC=` line and the `Pandoc` entry in `src/command/check/check.ts`'s `versionConstraints` array to the new version (this constraint tracks the bundled version exactly).
27-
- [ ] Ensure archives are upgraded.
28-
- [ ] Run `AWS_PROFILE=... ./package/src/quarto-bld update-pandoc PANDOC_VERSION` (without `--skip-archive`) to archive the binary to S3, configure it locally, and regenerate templates/variants.
29-
- [ ] Look at `git diff`, specifically for changes in Pandoc templates, and adjust as needed. As in Phase 1, a diff on an already-patched file means something was missed.
30-
- [ ] Run the `create-release.yml` dry-run signing/notarization gate (see `dev-docs/upgrade-dependencies.md`), then merge.
31-
32-
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 ours. (We can't just use `patch` because the templates have diverged too much)
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)
3311

3412
### Pandoc templates
3513

@@ -47,32 +25,6 @@ Partials:
4725
- Ours:
4826
- src/resources/formats/beamer/pandoc/common.latex
4927

50-
#### pdf / latex
51-
52-
- Pandoc's: src/resources/formats/pdf/pandoc/latex.template
53-
- Ours: src/resources/formats/pdf/pandoc/template.tex (see `llm-docs/pandoc-quarto-latex-templates.md` for the full partial breakdown, including `latex.common`/`common.latex`)
54-
55-
#### html
56-
57-
- Pandoc's: src/resources/formats/html/pandoc/html.template, src/resources/formats/html/pandoc/html.styles
58-
- Ours: src/resources/formats/html/pandoc/template.html, src/resources/formats/html/pandoc/styles.html
59-
60-
#### revealjs
61-
62-
- Pandoc's: src/resources/formats/revealjs/pandoc/revealjs.template
63-
- Ours: src/resources/formats/revealjs/pandoc/template.html
64-
65-
#### asciidoc
66-
67-
- Pandoc's: src/resources/formats/asciidoc/pandoc/asciidoc.template
68-
- Ours: src/resources/formats/asciidoc/pandoc/template.asciidoc
69-
70-
#### typst
71-
72-
See `llm-docs/pandoc-quarto-typst-templates.md` - typst has an extra wrinkle where Pandoc's own `template.typst` partial is also kept verbatim (same filename) alongside the renamed `typst.template`.
73-
74-
**All of the "Pandoc's" files above are dev-reference-only**: none of them are read by any TypeScript code path (confirmed via `grep -rn "<filename>" src/ --include="*.ts"` returning zero matches for each, across every format listed here). They exist purely so `git diff` against a fresh Pandoc checkout shows what changed upstream - patch the corresponding "Ours" file (or its own sub-partials, e.g. `tables.tex`, `toc.tex`) to actually change rendered behavior, and update the "Pandoc's" copy too so the next resync's diff stays meaningful. It's easy to update one and miss the other (or vice versa) since the filenames differ only by which segment comes first - use an unfiltered `ls`/`Glob **/*` on the directory when checking what's there, not an extension-filtered glob (e.g. `*.latex` silently excludes `latex.common`, which ends in `.common`). Because `writePandocTemplates` (in `package/src/common/update-pandoc.ts`) overwrites every "Pandoc's" copy wholesale on each run, never hand-fix an upstream bug in one of those reference copies - the change would silently vanish on the next resync, and the reference copy must stay byte-identical to upstream so the diff stays meaningful. (This session deliberately preserved a real upstream typo in `typst.template`'s divider-fallback polyfill for exactly this reason.) Behavioral fixes belong only in the corresponding "Ours" file (or its sub-partials).
75-
7628
## Manual steps
7729

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

‎dev-docs/upgrade-dependencies.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
Change version numbers in `./configuration` to correspond to new versions.
22

3-
Update hardcoded version strings in `src/command/check/check.ts` (`versionConstraints` array, ~line 249) so that they match the new versions in `configuration`. The `configuration` file warns about this in a comment. This constraint tracks the bundled version exactly (verified via history: `3.8.3` → `3.10.0` for Pandoc alongside the same PR's Dart Sass/Typst bumps), not a looser minimum floor.
4-
5-
**Pandoc specifically** has its own checklist: [update-pandoc-checklist.md](update-pandoc-checklist.md) - template resync (with a naming gotcha that's easy to miss), schema/lua-types checks, and a `QUARTO_PANDOC`-based CI path for smoke-testing a version before it's archived to S3.
3+
Update hardcoded version strings in `src/command/check/check.ts` (`versionConstraints` array, ~line 249) so that they match the new versions in `configuration`. The `configuration` file warns about this in a comment.
64

75
## Verify installer signing & notarization before merging (bundled binaries)
86

‎llm-docs/localization-architecture.md‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
main_commit: d30cdbb9e
3-
analyzed_date: 2026-07-23
2+
main_commit: eca40cdab
3+
analyzed_date: 2026-05-21
44
key_files:
55
- src/resources/language/_language.yml
66
- src/resources/language/_language-fr.yml
@@ -16,13 +16,14 @@ key_files:
1616
- src/resources/filters/modules/authors.lua
1717
- src/resources/filters/modules/callouts.lua
1818
- src/resources/filters/layout/meta.lua
19-
- src/resources/formats/html/pandoc/template.html
20-
- src/resources/formats/html/pandoc/toc.html
19+
- src/resources/formats/html/pandoc/html.template
2120
- src/resources/formats/html/pandoc/title-block.html
2221
- src/resources/formats/html/templates/title-metadata.html
22+
- src/resources/formats/pdf/pandoc/latex.template
2323
- src/resources/formats/pdf/pandoc/babel-lang.tex
2424
- src/resources/formats/pdf/pandoc/toc.tex
25-
- src/resources/formats/beamer/pandoc/toc.tex
25+
- src/resources/formats/beamer/pandoc/beamer.template
26+
- src/resources/formats/typst/pandoc/typst.template
2627
- src/resources/formats/typst/pandoc/quarto/typst-template.typ
2728
- src/resources/formats/typst/pandoc/quarto/typst-show.typ
2829
- src/resources/extension-subtrees/orange-book/_extensions/orange-book/typst-show.typ
@@ -150,9 +151,7 @@ These bypass both Pandoc metadata and Lua filters. The string lands directly in
150151

151152
`quarto.*` is an internal namespace. The user-facing override path for localized strings is the top-level `language:` YAML key (resolved by `formatLanguage`, already merged into `options.format.language` before the builder runs). The schema does not advertise `variables.quarto.*` as a user option, but the merge in `generateDefaults` honors a user-set value on collision: it deep-merges via `mergeConfigs` (`src/core/config.ts`) so user-supplied keys win at any nesting depth while all other localized values remain available. For example, a user setting `variables.quarto.language.crossref-ch-prefix: Bouquin` overrides only that one leaf — `$quarto.language.toc-title-document$` still resolves to the localized fallback. (Same helper is used in `src/core/language.ts:formatLanguage` to merge user-supplied `language:` onto `_language.yml` defaults.) A non-object `variables.quarto` (string, number, array) is ignored defensively. New contributors to this file should design around the `language:` path, not around the escape hatch.
152153

153-
From any Pandoc template — built-in (`template.html`, `template.tex`, `typst-template.typ`), extension partial, or custom user template — every localized key is then accessible as:
154-
155-
> **Naming note**: Quarto's actual, rendered templates are `template.html` (HTML), `template.tex` (LaTeX/PDF and Beamer), and `quarto/typst-template.typ` (Typst). The similarly-named `html.template`, `latex.template`, `beamer.template`, `typst.template`, `revealjs.template`, and `asciidoc.template` files elsewhere in these `pandoc/` directories are dev-reference-only copies of Pandoc's own default templates (zero references in `src/**/*.ts` — confirmed via grep), kept solely so a maintainer can diff them against a fresh Pandoc checkout during a version bump. Citations below point at the real, rendered files.
154+
From any Pandoc template — built-in (`html.template`, `latex.template`, `typst-template.typ`), extension partial, or custom user template — every localized key is then accessible as:
156155

157156
```pandoc
158157
$quarto.language.<key>$
@@ -174,9 +173,9 @@ It does **not** replace 2a — Lua filters still need `param("key")` because Pan
174173

175174
Localization paths used:
176175

177-
- **Document `lang` attribute**: `_language.yml` lookup not involved. `lang:` flows as Pandoc-native metadata, template renders `<html$if(lang)$ lang="$lang$" xml:lang="$lang$"$endif$>` (`template.html:2`).
178-
- **TOC title**: `$toc-title$` resolved via channel 2b. Used in `toc.html:3`.
179-
- **Abstract title**: `$abstract-title$` resolved via 2b. Used in `title-block.html:15`.
176+
- **Document `lang` attribute**: `_language.yml` lookup not involved. `lang:` flows as Pandoc-native metadata, template renders `<html lang="$lang$" xml:lang="$lang$">` (`html.template:2`).
177+
- **TOC title**: `$toc-title$` resolved via channel 2b. Used in `html.template:60`, `toc.html:3`.
178+
- **Abstract title**: `$abstract-title$` resolved via 2b. Used in `html.template:51`, `title-block.html:15`.
180179
- **Title block labels** (`Authors`, `Affiliations`, `Published`, `Modified`, `Doi`, `Abstract`, `Keywords`): `$labels.*$` written into meta by `modules/authors.lua:854-913` (`computeLabels`). Templates: `title-metadata.html:3,4,32,43,52,61,74,83`, `manuscript/title-metadata.html:6,7,37,48,57,66,83,92`.
181180
- **Crossref text** (`Figure 1.1`, `Table 2.1`): assembled in Lua by `crossref/format.lua` using `title()` / `refPrefix()` which call `param("crossref-<type>-title"/"-prefix")`. Written as inline text directly into the AST. By the time Pandoc renders HTML, the localized prefix is already document content.
182181
- **Callout titles** (`Tip`, `Note`, etc.): `modules/callouts.lua:15,185` reads `param("callout-<type>-title", default)`, writes into the callout node.
@@ -192,7 +191,7 @@ Three localization paths layered:
192191

193192
Other Lua filters use `metaInjectLatex` for non-language LaTeX customization (`crossref/custom.lua:78`, `layout/meta.lua`, `quarto-post/landscape.lua`, etc. — they inject packages or styling, not localized strings).
194193

195-
3. **Pandoc template `$var$`** — `pdf/pandoc/toc.tex:2-3` uses `$toc-title$` to set `\contentsname`. Beamer's `beamer/pandoc/toc.tex:2-3` does the same.
194+
3. **Pandoc template `$var$`** — `pdf/pandoc/toc.tex:3` and `pdf/pandoc/latex.template:93-94` use `$toc-title$` to set `\contentsname`. Beamer templates (`beamer/pandoc/beamer.template:146-151`, `beamer/pandoc/toc.tex:3`) likewise.
196195

197196
PDF-side TS code does not read `format.language` directly except `src/format/pdf/format-pdf.ts:242` which registers `"babel-lang"` as a Quarto partial.
198197

0 commit comments

Comments
 (0)