HTML cross-reference supplement for appendix sections only ("Chapter" → "Appendix")

[ratnanil]

Description

In a Quarto book, appendix sections get letter-based numbering (A.1, B.2…). I want @sec-app pointing into an appendix to render as "Appendix A.1" while regular section refs keep "Chapter 3.2". PDF/Typst output is solved via a Typst show ref: rule, in HTML its a bit harder.

Minimal example

_quarto.yml:

project:
  type: book
book:
  title: "Test"
  chapters: [index.qmd]
  appendices: [appendix.qmd]
crossref:
  chapters: true
format:
  html: default

index.qmd:

# Introduction
See @sec-app for details.

appendix.qmd:

# Appendix
## Analysis {#sec-app}
Content.

Renders as: See Chapter A.1 for details.
Desired: See Appendix A.1 for details.

What we tried

1. Lua Link filter at post-quarto — the filter fires, but el.content is still the raw section ID (sec-app), not the resolved text. The supplement ("Chapter A.1") is generated after all filter stages.

2. Lua Link filter at post-render — same result, still raw ID.

3. crossref-sec-title: "Appendix" — changes all section refs, not just appendix ones.

Current workaround

A post-quarto Lua filter adds class="appendix-ref" to links whose target URL contains the appendix section ID (the URL is available at that stage even though the display text isn't). A JS snippet in include-after-body then swaps the word on DOMContentLoaded:

document.querySelectorAll('a.appendix-ref span').forEach(function(span) {
  span.textContent = span.textContent.replace(/^Chapter/, 'Appendix');
});

Question

Is there a Quarto-native way to customise section cross references, similar to the custom floats? Or is there a filter stage where the resolved display text is available as an AST element? Something like a crossref-apx-sec-title language key would be the ideal solution.

[mcanouil]

Thanks for the detailed write-up, in particular the list of what you already tried.

I cannot reproduce the Chapter A.1 output

Which Quarto version do you use?
Please add the output of quarto check.

I ran your example on the current development build (d742b9083).
I added a label on the appendix chapter heading, so that both cases show in one render.

appendix.qmd:

# Appendix {#sec-apxchap}

## Analysis {#sec-app}

Content.

index.qmd:

# Introduction

See @sec-app for details.
See @sec-apxchap for details.

The rendered index.html gives this:

<a href="appendix.html#sec-app" class="quarto-xref"><span>Section A.1</span></a>
<a href="appendix.html" class="quarto-xref"><span>Appendix A</span></a>

The section reference gives Section A.1, not Chapter A.1.
The chapter-level reference gives Appendix A, which is correct.
That chapter-level behaviour was corrected a long time ago, in Quarto 1.1.
See:

• When cross-referencing Appendix, use "Appendix X" instead of "Chapter X".  #1705
• How to cross reference an Appendix #1820

---

Why Appendix A.1 is not available today

Three language keys control the prefix of a section cross-reference:

language:
  crossref-ch-prefix: "Chapter"
  crossref-apx-prefix: "Appendix"
  crossref-sec-prefix: "Section"

Quarto uses crossref-apx-prefix only when the target is a chapter-level heading inside an appendix.
Every deeper heading uses crossref-sec-prefix, in an appendix or not.

• https://github.com/quarto-dev/quarto-cli/blob/d742b9083/src/project/types/book/book-crossrefs.ts#L307-L312
• https://github.com/quarto-dev/quarto-cli/blob/d742b9083/src/project/types/book/book-crossrefs.ts#L202-L208

There is no crossref-apx-sec-prefix key.
Your idea of a crossref-apx-sec-title key does not exist yet, so your reading is correct.

One small correction on your third attempt: crossref-sec-title is not a Quarto key.
The key that acts on section references is crossref-sec-prefix, and it is global, as you observed.

---

Related items

• crossref values are displayed in html but not in pdf #11772 tracks a related defect in the same code path: crossref.appendix-title and crossref.appendix-delim have no effect, and only language: crossref-apx-prefix acts on the reference.
• In quarto book, how can I refer to appendices as "attachments"? #11950 shows how to rename appendix chapter references with crossref-apx-prefix.
• FR: customization options for cross references in book project #2356 added custom prefixes for floats, such as Table S1, but not for sections.

None of these cover sections inside an appendix.

---

Next step

Please confirm your Quarto version first.
If you see Chapter A.1 on a recent version, that is a separate defect and it needs an issue.

If you see Section A.1 as I do, then your request is a feature request for an appendix-aware prefix on sections below chapter level.
Your JavaScript workaround is the only route in HTML at the moment.