`number-sections: True` misbehaves slightly when appendix sections are present

[GuillaumeDehaene]

Bug description

number-sections: true numbers all sections in the order in which they appear in the source markdown document.

however, this conflicts with the {.appendix} class command which sends the section to the appendix of the document.

Steps to reproduce

Here is a minimal example:

---
format: html
number-sections: true
---

# Section A

# Appendix {.appendix}

# Section B

Expected behavior

I would expect the result to render as

1. Section A
2. Section B
3. Appendix

Actual behavior

Instead the numbers are mangled

1. Section A
3. Section B
2. Appendix

Depending on the underlying code:

• if the fix is too complex, it's probably best to just mention the poor interaction in the docs: the user can fix it by reordering their document
• from the outside, it looks like .appendix should modify the order of the sections in the pandoc AST. If so, maybe it's possible to fix this in a flash by just re-ordering the sections

Your environment

• IDE: vscode
• OS: windows 11

Quarto check output

Quarto 1.5.45
[>] Checking versions of quarto binary dependencies...
Pandoc version 3.2.0: OK
Dart Sass version 1.70.0: OK
Deno version 1.41.0: OK
Typst version 0.11.0: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
Version: 1.5.45
Path: C:\Users\Guillaume\AppData\Local\Programs\Quarto\bin
CodePage: 1252

[>] Checking tools....................OK
TinyTeX: v2024.06
Chromium: (not installed)

[>] Checking LaTeX....................OK
Using: TinyTex
Path: C:\Users\Guillaume\AppData\Roaming\TinyTeX\bin\windows
Version: 2024

[>] Checking basic markdown render....OK

[>] Checking Python 3 installation....OK
Version: 3.12.4
Path: d:/Desktop/Dojo/quarto_bug_report_listings/.venv/Scripts/python.exe
Jupyter: 5.7.2
Kernels: python3

[>] Checking Jupyter engine render....OK

[>] Checking R installation...........(None)

  Unable to locate an installed version of R.
  Install R from https://cloud.r-project.org/

[mcanouil]

For which format you observed this? HTML?

[mcanouil]

From few quick tests on format: html, it's an "old" behaviour.

FYI, the current documentation: https://quarto.org/docs/authoring/appendices.html#custom-appendix-sections

[GuillaumeDehaene]

Hello

yes, this is an html-only behavior. I have edited the minimal example to add format: html. As far as I can tell, the number-sections option only works there. Sections are numbered in some other fashion in the other formats, I believe?

I'm not quite sure what you mean when you say it's "old"? the number-sections option is mentioned here (as a requirement for cross-refs to sections) https://quarto.org/docs/authoring/cross-references.html#sections as well as in the general html reference

[mcanouil]

I meant the issue is not a new one and was never caught before so thanks!

[cderv]

This is bad. Glad you caught that !

We should probably add a .unnumbered class when .appendix is set for Pandoc to not number, and then maybe number appendix independently 🤔

---
format: html
number-sections: true
---

# Section A

Content

# Appendix {.appendix .unnumbered}

Content

# Section B

Content

[cderv]

Traced this to sections.lua: the appendix-numbering path (skip regular numbering, apply the "Appendix" prefix) is gated on level == 1 and currentFileMetadataState().appendix, which is file-level metadata used for book/manuscript appendix files. It never gets set from the .appendix class on a single-document heading, so those headings fall through to ordinary body numbering and consume a slot from the body sequence.

quarto-cli/src/resources/filters/crossref/sections.lua

Lines 53 to 57 in 663c449

	if (numberSections() and level <= numberDepth()) then
	local appendix = (level == 1) and currentFileMetadataState().appendix
	if appendix then
	el.content:insert(1, pandoc.Space())
	tprepend(el.content, crossrefOption("appendix-delim", stringToInlines(" —")))

The HTML-side appendix mover (format-html-appendix.ts) only relocates section.appendix DOM nodes after render — it doesn't touch numbering, so there's nothing today connecting the .appendix class to the numbering logic.

Closing #10418 as a duplicate (custom-appendix + toc variant, same root cause) — merging in here since this issue has the older MRE and the fix direction already sketched above. Also related: #10419 (appendix-style: plain losing header numbers).