Add chapter + paragraph to figure numbering

[rwaaijman]

Description

Is it possible to add besides chapter also H2, H3, etc to the figure numbering. So it is clear to what paragraph a figure belongs to? So the second figure number would be 1.1.1.2 in # > ## > ###

for example:

 ---
title: "Example"
format: html
    
fig-cap-location: top
crossref: 
    chapters: true
    fig-title: Fig
    title-delim: "."

number-sections: true
number-depth: 3

execute: 
  echo: false
---

# Chapter
Example numbering figures (@fig-2)

## paragraph

```{r}
#| label: fig-1
#| fig-cap: cap

df <- data.frame(x = 1:10, y = 11:20)
plot(df$x,df$y)
```

# Chapter
## paragraph
### sub-paragraph
Preferably the Fig-number would be 2.1.1.1 (first figure in heading3)
```{r}
#| label: fig-2
#| fig-cap: This is a test

df <- data.frame(x = 1:10, y = 11:20)
plot(df$x,df$y)
```

[mcanouil]

Not natively.

---

As this is more of a question than a feature request, could you change the category to Q&A?

[rwaaijman]

this would be feature request, since it is not possible yet.
It would be worthfull if you could see directly to which chapter and paragraph a figure belongs to

[mcanouil]

Could you clarify your feature request then.
You are talking about "chapters", are you implying book projects? Or are you talking about level one heading in single document in HTML format?

The more details you give, the more chances it gets to be implemented.
Vague feature requests tend to be forgotten.

[rwaaijman]

And yes indeed, this numbering is a book project. We would like to have the numbering.
So suppose I have a figure in a book project in charter 2, heading1, sub-heading 3, I would like the number of the first figure 2.1.3.1

For example, this is a book project: https://dashboards.cbs.nl/longreads/VIA_2025/hoofdstukken/2_positiearbeidsmarkt.html#fig-1
We would like to have this figurenumber Figure 2.2.1 instead of 2.4 (and even so for tables)

[mcanouil]

From my understanding of the Quarto CLI source code¹, the infrastructure for multi-level hierarchical numbering already exists but is limited intentionally or it is an oversight during development.

What Currently Happens

1. All 7 heading levels are tracked in crossref.index.section:

   • quarto-cli/src/resources/filters/crossref/index.lua

     Line 21 in 333f9bd

     section = sectionOffsets:clone(),

2. Full section arrays are stored with each figure entry:

   • quarto-cli/src/resources/filters/crossref/index.lua

     Lines 53 to 56 in 333f9bd

     	return {
     	section = crossref.index.section:clone(),
     	order = nextOrder
     	}

3. But only chapter level is used due to two policy gates:

   • quarto-cli/src/resources/filters/crossref/options.lua

     Lines 9 to 10 in 333f9bd

     	if crossrefOption("chapters", false) then
     	crossref.maxHeading = 1

     (sets maxHeading = 1 when chapters: true)

   • quarto-cli/src/resources/filters/crossref/format.lua

     Lines 142 to 153 in 333f9bd

     	if not crossrefOption("chapters", false) then
     	section = nil
     	elseif section ~= nil and section[1] == 0 then
     	section = nil
     	elseif crossref.maxHeading ~= 1 then
     	section = nil
     	end
     	-- return a pandoc.Str w/ chapter prefix (if any)
     	local function resolve(num)
     	if section then
     	local sectionIndex = section[1]

     (only uses section[1] for the prefix)

What a Native Implementation Would Require

A Quarto CLI implementation would need minimal changes I think:

1. Add a new option (e.g., crossref-depth: 3) to specify how many heading levels to include.
2. Modify options.lua to set maxHeading based on this option:
   • https://github.com/quarto-dev/quarto-cli/blob/333f9bd45225a0bc8fa931350626f7988a588f27/src/resources/filters/crossref/options.lua
3. Modify format.lua to iterate through section[1..depth] instead of just section[1]:

   • quarto-cli/src/resources/filters/crossref/format.lua

     Line 153 in 333f9bd

     local sectionIndex = section[1]

The policy gates apply to all output formats (HTML, PDF, DOCX, etc.) since the Lua filters run during AST processing before format-specific rendering.

Footnotes

1. with a bit of help from DeepWiki ↩

[rwaaijman]

Thanks for the suggestions! I'm not sure if I will be able your suggestion, but I'm going to try.

[mcanouil]

The suggestion is not necessarily for you to take on.