Consistency between PDF and HTML regarding TOC and chapter/table/figure numbering

[MarcoPortmann]

Description

I want to publish a scientific article as an HTML page and offer an identical PDF version. The Quarto script below produces a pdf document as I envision it. However, despite some time spent learning Lua filters, I have not been able to create an HTML document that matches the PDF.

---
appendix-style: plain
references:
  - id: lamport1994latex
    type: book
    title: "LaTeX: A Document Preparation System"
    author:
      - family: Lamport
        given: Leslie
    issued:
      year: 1994
    publisher: "Addison-Wesley"
format: 
  html:
    toc: true
    toc-depth: 3
    number-sections: true
  pdf:
    documentclass: scrreport
    toc: true
    toc-depth: 3
    number-sections: true
---

```{r message=TRUE, include=FALSE}
library(tidyverse)

```


# Executive Summary {-}

{{< lipsum 1 >}}

\pagenumbering{arabic}

# Introduction

A reference [@lamport1994latex].

## Text

{{< lipsum 1 >}}

## Subtitle

{{< lipsum 1 >}}

```{r, echo=F}
#| label: fig-one
#| fig-cap: "Test Figure"


dataset <- mtcars
dataset$carname <- row.names(mtcars)

ggplot(
  data = dataset,
  mapping = aes(
    x = wt, y = qsec, color = disp,
    tooltip = carname, data_id = carname
  )
) +
  geom_point() +
  theme_minimal()

```

This is @fig-one.

\appendix
\renewcommand\thefigure{A.\arabic{figure}}
\setcounter{figure}{0}
\renewcommand\thetable{A.\arabic{table}}
\setcounter{table}{0}

# Appendix {.appendix}

{{< lipsum 1 >}}

## Appendix Subtitle

{{< lipsum 1 >}}

```{r, echo=F}
#| label: fig-two
#| fig-cap: "Another Test Figure"


dataset <- mtcars
dataset$carname <- row.names(mtcars)

ggplot(
  data = dataset,
  mapping = aes(
    x = wt, y = qsec, color = disp
  )
) +
  geom_point() +
  theme_minimal()

```

This is @fig-two.

# References {.appendix}

::: {#refs}
:::

The pdf TOC looks like this:

This is the html TOC:

There are three inconsistencies:

1. Appendix sections {.appendix} do not appear in the TOC.
2. Appendices are typically numbered alphabetically, while the main sections use Arabic numerals.
3. The numbering of tables, figures, and formulas often includes the chapter number (see also Chapter number as part of the image and table labeling in format html #10011).

I am aware that some of these issues could be resolved with a Quarto book. However, I would find it extremely useful if Quarto offered these functionalities for simple HTML documents with just a single qmd file.

The most significant benefit, in my opinion, would be if the appendix chapters appeared in the TOC (1). I do not understand why this is not the default behavior. Regarding the alphabetical numbering of appendices (2) and the chapter-wise numbering of figures and tables (3), I assume users have different preferences (and 2 & 3 are probably easier to implement via custom Lua filters than 1). But it would still be nice to have the option of easily selecting a corresponding numbering from the yaml header.

Wouldn't it be desirable, for the sake of consistency between PDF and HTML formats, to enable the creation of an HTML article from a single qmd file that closely matches the PDF output in terms of the TOC and the numbering of headings, tables, and figures?

[cderv]

Appendix sections {.appendix} do not appear in the TOC.

I believe it has been remove from TOC on purpose, at least for the default style

• Custom appendix sections appear in table of contents #3113

Maybe there should be an option, or it should take appendix-style in consideration

Let's note that there is the inverse demand of removing the appendices from TOC in PDF:

• Latex: Possiblity to remove 'Appendices' part title in table of contents #1096

Anyhow, you can opt-out appendix processing by using appendix-style: none and this should consider your header as usual Markdown header, by putting them in TOC and with numbering.

Appendices are typically numbered alphabetically, while the main sections use Arabic numerals.

There is indeed currently now way in single document. One would need to use JS script probably or Lua filter to tweak the numbering.

We do process appendicies differently in Books though. Books are really the format where the notion of Chapters is considered, and so Appendix chapters is.

Those are good feedback - we'll add them to backlog. Thanks !

[MarcoPortmann]

Thank you ,@cderv, for adding the feedback to backlog and for the helpful hint:

Anyhow, you can opt-out appendix processing by using appendix-style: none and this should consider your header as usual Markdown header, by putting them in TOC and with numbering.

Thanks to this, I was able to create a Lua filter that alphabetically numbers the appendices in HTML output, consistent with the PDF output. There are certainly areas for improvement (I have little experience with Lua). For others who might be interested, I’m sharing the code:

Test qmd:

---
appendix-style: none
references:
  - id: lamport1994latex
    type: book
    title: "LaTeX: A Document Preparation System"
    author:
      - family: Lamport
        given: Leslie
    issued:
      year: 1994
    publisher: "Addison-Wesley"
format: 
  html:
    toc: true
    toc-depth: 3
    number-sections: true
    filters:
     - at: post-quarto
       path: appendix_numbering.lua  
  pdf:
    documentclass: scrreport
    toc: true
    toc-depth: 3
    number-sections: true
---

```{r}
#| message: true
#| include: false

library(tidyverse)

```


# Executive Summary {-}

{{< lipsum 1 >}}

\pagenumbering{arabic}

# Introduction
 
A reference [@lamport1994latex]. @sec-mainsub, @sec-app, @sec-app2, @sec-app3.

## Text

{{< lipsum 1 >}}

## Subtitle{#sec-mainsub}

{{< lipsum 1 >}}

```{r}
#| label: fig-one
#| fig-cap: "Test Figure"
#| echo: false

dataset <- mtcars
dataset$carname <- row.names(mtcars)

ggplot(
  data = dataset,
  mapping = aes(
    x = wt, y = qsec, color = disp
  )
) +
  geom_point() +
  theme_minimal()

```

This is @fig-one.

```{=latex}
\appendix
\renewcommand\thefigure{A.\arabic{figure}}
\setcounter{figure}{0}
\renewcommand\thetable{A.\arabic{table}}
\setcounter{table}{0}
```

# Appendix {.appendix #sec-app}

{{< lipsum 1 >}}

## Appendix Subtitle {.appendix #sec-app2}

{{< lipsum 1 >}}

```{r}
#| label: fig-two
#| fig-cap: "Another Test Figure"
#| echo: false

dataset <- mtcars
dataset$carname <- row.names(mtcars)

ggplot(
  data = dataset,
  mapping = aes(
    x = wt, y = qsec, color = disp
  )
) +
  geom_point() +
  theme_minimal()
```

This is @fig-two.

### Appendix Subsubtitle {.appendix #sec-app3}

# References {.appendix}

::: {#refs}
:::

appendix_numbering.lua:

local appendix = false
local appendix_counter = 0
local chapters = {}
local current_appendix_label = ""

-- First pass: Collect chapter IDs
function collectChapters(el)
if el.level == 1 then
if el.classes:includes("appendix") then
appendix_counter = appendix_counter + 1
current_appendix_label = string.char(64 + appendix_counter)
chapters[el.identifier] = current_appendix_label
appendix = true
else
  appendix = false
end
elseif appendix then
-- Adjust numbering for subchapters based on original numbering
local original_number = pandoc.utils.stringify(el.content):match("^%d+[%.%d]*")
if original_number then
local subchapter_label = current_appendix_label .. original_number:gsub("^%d+", "")
chapters[el.identifier] = subchapter_label
local new_text = subchapter_label .. " " .. pandoc.utils.stringify(el.content):gsub("^%d+[%.%d]*%s*", "")
el.content = {pandoc.Str(new_text)}
end
end
return el
end

-- Second pass: Adjust chapter numbers and links
function processHeaders(el)
if el.level == 1 then
if el.classes:includes("appendix") then
local text = pandoc.utils.stringify(el.content)
local new_text = chapters[el.identifier] .. " " .. text:gsub("^%d+[%.%d]*%s*", "")
el.content = {pandoc.Str(new_text)}
appendix = true
else
  appendix = false
end
end
return el
end

function processLinks(el)
local target = el.target:match("#(.*)")
if target and chapters[target] then
el.content = {pandoc.Str("appendix " .. chapters[target])}
end
return el
end

-- Define Pandoc passes
return {
  { Header = collectChapters },
  { Header = processHeaders, Link = processLinks }
}

This produces:

[mcanouil]

@MarcoPortmann few suggestions to avoid possible future headaches.

• do not mix syntax for cell options. They override each other.
  Quarto recommends YAML.

```{r, echo=F}
#| label: fig-two
#| fig-cap: "Another Test Figure"
...
```

Would become

```{r}
#| label: fig-two
#| fig-cap: "Another Test Figure"
#| echo: false
...
```

• use raw block to enclose raw code such as LaTeX. That's the only way to ensure Quarto/Pandoc won't parse/read it the wrong way.

https://quarto.org/docs/authoring/markdown-basics.html#raw-content

```{=latex}
\appendix
\renewcommand\thefigure{A.\arabic{figure}}
\setcounter{figure}{0}
\renewcommand\thetable{A.\arabic{table}}
\setcounter{table}{0}
```

[MarcoPortmann]

Thank you for the suggestions; I've revised the code accordingly.