Skip to content

fix(crossref): apply appendix-title to appendix cross-references#14617

Closed
cderv wants to merge 2 commits into
mainfrom
fix/issue-11772
Closed

fix(crossref): apply appendix-title to appendix cross-references#14617
cderv wants to merge 2 commits into
mainfrom
fix/issue-11772

Conversation

@cderv

@cderv cderv commented Jun 23, 2026

Copy link
Copy Markdown
Member

When a book sets crossref.appendix-title, the appendix chapter heading uses it (e.g. Whatever A: Summary in HTML), but cross-references to that appendix render the default Appendix N prefix in PDF — the configured title is ignored. The language: crossref-apx-prefix workaround from the issue only papers over the symptom and does nothing for appendix-delim.

Root Cause

The appendix cross-reference prefix is built from language.crossref-apx-prefix alone, never crossref.appendix-title. Two independent code paths build it:

  1. Lua refPrefix (src/resources/filters/crossref/format.lua) — PDF, and HTML same-file references.
  2. TS formatCrossref (src/project/types/book/book-crossrefs.ts) — HTML cross-file references resolved at the book post-render stage.

Fix

Both paths now prefer crossref.appendix-title when set, falling back to the language string — mirroring the precedence formatChapterTitle already uses for the appendix heading. Behavior is unchanged when appendix-title is unset.

The HTML cross-file path only resolves after a full project render, so its smoke-all test uses render-project: true. The project pre-render builds only declared formats, so the fixture declares format: html; this render-project behavior is now documented in the testing rules and llm-docs.

The PDF/LaTeX appendix chapter heading itself (as opposed to cross-references) still ignores appendix-title/appendix-delim; matching the HTML Whatever A: Summary heading in LaTeX needs \appendixname/KOMA work and is tracked separately in #14616.

Test Plan

  • Book PDF: an @sec- reference to an appendix shows See Whatever A, not See Appendix A
  • Book HTML: a cross-file appendix reference from a numbered chapter shows the configured title
  • With appendix-title unset: appendix cross-references unchanged (default Appendix N)

Fixes #11772

cderv added 2 commits June 23, 2026 17:58
Documents the bug before the fix: in a PDF book, an appendix
cross-reference ignores `crossref.appendix-title` and falls back to the
default "Appendix" prefix, whereas HTML honors it. Only the
`language: crossref-apx-prefix` key currently drives the PDF prefix.

The test asserts the custom prefix ("Whatever") reaches the appendix
cross-reference in the merged book .tex. It is RED on current main and
turns green once the cross-reference path consults the crossref option.

Test block lives on index.qmd because the smoke-all harness only
resolves the merged book .tex when the test file is the book index.
)

crossref.appendix-title and crossref.appendix-delim styled the appendix
chapter heading (via formatChapterTitle) but the appendix cross-reference
prefix was built solely from language.crossref-apx-prefix, so @sec-refs to
an appendix rendered the default "Appendix N" regardless of appendix-title.
mcanouil's language: crossref-apx-prefix workaround only papered over this.

Two independent code paths build that prefix, both now prefer
crossref.appendix-title (falling back to the language string), mirroring
formatChapterTitle's precedence:
- Lua refPrefix (crossref/format.lua): PDF, and HTML same-file references.
- TS formatCrossref (book-crossrefs.ts): HTML cross-file references resolved
  at the book post-render stage.

The HTML cross-file path can only be exercised after a full project render,
so its smoke-all test uses render-project: true; the project pre-render only
builds declared formats, so the fixture declares format: html. Documented
this render-project behavior in the testing rules and llm-docs.

The PDF/LaTeX appendix chapter heading itself (not the cross-reference) still
ignores appendix-title/appendix-delim; that needs appendixname/KOMA work and
is tracked separately in #14616.
@posit-snyk-bot

posit-snyk-bot commented Jun 23, 2026

Copy link
Copy Markdown
Collaborator

Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
Open Source Security 0 0 0 0 0 issues
Licenses 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

@cderv

cderv commented Jun 23, 2026

Copy link
Copy Markdown
Member Author

Closing this — on re-reading the issue, it solves the wrong thing. Reviewing the code it does not seem right to use appendix-title as the prefix.

The reported problem is the appendix chapter heading in PDF: HTML shows Attachment A: Details, PDF shows A Details. This PR instead changes the appendix cross-reference prefix, which was already consistent between HTML and PDF and isn't what the issue is about. crossref.appendix-title is the heading label; the cross-reference prefix is the separate localized crossref-apx-prefix, so routing the title into cross-references also risks overriding the localized prefix under lang:.

I'll reopen work focused on the PDF appendix heading itself.

@cderv cderv closed this Jun 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

crossref values are displayed in html but not in pdf

2 participants