Prep Pandoc 3.10.1 update, gate version bump behind S3 archival#14723
Open
cderv wants to merge 13 commits into
Open
Prep Pandoc 3.10.1 update, gate version bump behind S3 archival#14723cderv wants to merge 13 commits into
cderv wants to merge 13 commits into
Conversation
Collaborator
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
Pandoc 3.10.1 changed common.latex (caption package + spacing for tables), default.typst (native terms hanging-indent and divider() polyfill, quoted keywords), and styles.html (dropped hardcoded print font-size) relative to 3.10.0. Ported the same changes into Quarto's copies, verified byte-identical against the upstream 3.10.1 source. Not gated on a bundled-binary version bump: tables.tex is Quarto's own always-loaded LaTeX/Beamer partial, so this takes effect immediately regardless of which Pandoc binary renders. typst.template and html.styles are pandoc-quarto template resync only; the QUARTO_VERSION bump itself is a separate, gated step.
typst.template/template.typst were documented as a custom-template fallback path, but they're never referenced by any TypeScript code - they only exist so a maintainer can diff them against a fresh Pandoc checkout during the update-pandoc process. Corrected that, and added a note that Pandoc's typst writer can change body-level output (e.g. horizontalrule -> divider()) independently of any template file, so a clean template diff alone isn't proof a Pandoc bump has no effect. The LaTeX doc was missing document-metadata.latex (added in Quarto 1.7 for Pandoc 3.6.3's PDF/A-UA-X support): absent from the file table, the partialNamesPandoc sample, and the invocation order (it's actually called first). Also noted update-pandoc.ts's own templateDirFiles mapping doesn't copy this file, so the script itself undercounts relative to what format-pdf.ts wires up. Both files gain main_commit/analyzed_date/key_files frontmatter per the llm-docs staleness-check convention.
Missed these in the earlier tables.tex resync: latex.common (both pdf and beamer) is Pandoc's own common.latex kept verbatim for future-diff purposes, same as typst.template - not wired into any partial list, so it was still byte-for-byte Pandoc 3.10.0. A glob pattern filtered on *.latex silently excluded it since it ends in .common, which is what let this slip past the earlier pass. Both files verified byte-identical to Pandoc 3.10.1's common.latex.
Bumping a bundled binary can't be tested in CI until it's archived to S3, since configure only ever downloads what's already archived there. This adds a pandoc-override-version workflow_dispatch input that installs the given release via r-lib/actions/setup-pandoc and points quarto at it through QUARTO_PANDOC for that run only - the archived/configured version, and every other trigger of this workflow, is unaffected. Lets template/rendering changes be smoke-tested against an unarchived Pandoc release before anyone with S3 access has to get involved.
The earlier html.styles fix patched Pandoc's dev-reference-only copy (html.template's sibling), not styles.html - the actual file wired up in format-html.ts and rendered whenever theme:pandoc is set. Same mistake as the latex.common miss: an extension-based assumption about which file is "ours" vs Pandoc's reference copy. styles.html has its own local divergences from Pandoc's stock CSS (existing height/auto typo, a simplified table-caption block, custom checkbox margin per #4556), so this only removes the stale font-size: 12pt rule rather than re-syncing the whole file. Verified via a real render with theme: pandoc (the only path that sets document-css: true and actually includes this file) that the rule is now gone from rendered output.
The dev-reference-only pattern (Pandoc's own template copied in verbatim, unreferenced by any TS code, kept only for future-diff purposes) turned out to apply to every format with a pandoc/ resource dir, not just typst and latex: beamer, html (both html.template and html.styles), revealjs, and asciidoc all have the same split between a reference copy and Quarto's actual wired-up template. jats is the exception - template.xml is entirely Quarto-authored, no Pandoc reference copy exists. update-pandoc-checklist.md now lists the per-format file pairs and states the naming gotcha explicitly (extension-filtered globs like *.latex silently exclude latex.common). The rule pointer's paths now cover every affected format directory so it actually fires. localization-architecture.md had four citations pointing at dead reference-copy files (html.template, latex.template, beamer.template) to describe behavior that's actually in the live template.html, template.tex, and toc.tex - corrected each and added a naming-note caveat so the same mix-up doesn't recur here.
Editing configuration or check.ts (the first files touched in any bundled-binary bump) had no rule surfacing dev-docs/upgrade- dependencies.md, unlike editing a pandoc/ template dir which already routes to the Pandoc-specific checklist. A bump starting at configuration - before touching any template file - got no automatic pointer at all. Also cross-referenced update-pandoc-checklist.md from upgrade- dependencies.md's general Pandoc mention, and noted that check.ts's version constraint tracks the bundled version exactly rather than a looser floor (confirmed via the 3.8.3 -> 3.10.0 history).
Splits the Pandoc update into an S3-free prep phase. --skip-archive regenerates templates and format-extension.ts from a QUARTO_PANDOC binary without archiving, configuring, or rewriting configuration, so contributors without S3 credentials can prepare and verify a bump. QUARTO_PANDOC is required so writeVariants cannot silently regenerate format-extension.ts from a stale configured Pandoc. Result is left as an uncommitted diff.
Names Phase 1 (--skip-archive prep, no S3, anyone) and Phase 2 (archival by an S3 holder before merge), records the QUARTO_PANDOC requirement, and states the reference-copy invariant: those copies are regenerated wholesale, so upstream bugs must never be hand-fixed there.
Moves the 4 inline QUARTO_PANDOC-override steps out of test-smokes.yml into .github/workflows/actions/pandoc-override, matching the existing composite-action pattern (quarto-dev, sign-files). All 4 steps gate on the same input consistently instead of being scattered inline in the workflow.
The confirm step forced shell: bash (Git Bash/MSYS), which doesn't apply Windows PATHEXT and can't resolve a bare quarto when only quarto.cmd is on PATH - failed with exit 127 command not found on the first CI dispatch. Splits the step per OS like the existing QUARTO_PANDOC-setting steps: bash on Linux, pwsh on Windows (which does apply PATHEXT).
Neither .github/actions/ nor .github/workflows/actions/ had a reference listing what each composite action does. Adds one README per directory; doesn't merge or reorganize the two locations.
toolsPath() (src/core/resources.ts) silently falls back to the bundled/configured Pandoc if QUARTO_PANDOC is unset, nonexistent, or otherwise fails to resolve - only a warnOnce, no error. The prior preflight only warned on a version mismatch and continued into writeVariants(), which would then silently regenerate format-extension.ts from the wrong (old, bundled) Pandoc - the exact corruption --skip-archive exists to prevent. Both the unreadable-version and mismatched-version cases now abort instead of warning.
cderv
force-pushed
the
update-pandoc-3.10.1
branch
from
July 23, 2026 17:27
9d53b85 to
1ac5a40
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pandoc released 3.10.1. Quarto currently bundles 3.10.0 (landed in #14664). Actually bumping the bundled version means archiving the new binary to S3 and, since main just recovered from a bundled-binary notarization break (#14718), running the release signing/notarization dry-run before merging. Neither of those happens in this PR - it only prepares, so the eventual bump is lower-risk and can be done incrementally by whoever holds S3 credentials.
Resyncs the Pandoc-derived template files that changed between 3.10.0 and 3.10.1:
tables.tex(pdf and beamer),typst.template, andhtml/pandoc/styles.html, each verified byte-exact against upstream and via real renders.Fixes stale doc and
llm-docsclaims about which template files are Quarto's wired-up copies versus Pandoc's dev-reference-only copies, across every format. The naming trap those docs describe (latex.commonvscommon.latex,styles.htmlvshtml.styles) caught two patches in this same prep before the doc audit caught it.Adds an opt-in
pandoc-override-versioninput totest-smokes.ymlso a not-yet-archived Pandoc version can be smoke-tested viaQUARTO_PANDOCwithout needing S3 access.Adds
--skip-archivetoquarto-bld update-pandocso the template andformat-extension.tsregeneration can be prepared and verified against aQUARTO_PANDOCbinary without S3 credentials, leaving the result as an uncommitted diff to review - a safety net against the same naming trap for future updates.configurationstays pinned at 3.10.0. The version bump, S3 archival, and release dry-run are Phase 2 indev-docs/update-pandoc-checklist.md, for whoever holds S3 credentials to do right before merge.Test Plan
test-smokes.ymlwithpandoc-override-version: 3.10.1(scoped to typst/latex/table buckets) and confirm a clean run./package/src/quarto-bld update-pandoc 3.10.1 --skip-archivewithQUARTO_PANDOCpointed at a 3.10.1 binary - expect an empty diff, confirming the templates above already match