Tricky issues with adding an appendix to an article

[andrewheiss]

When writing academic journal articles, it is common to have a supplemental appendix with extra figures/tables/math/etc.

Quarto supports a couple different ways for handling appendices, but they create inconsistent output across formats and I can’t figure out how to get them consistent :(

My ultimate goal is to get text that looks like this in both HTML and PDF (and ideally Word too):

See Table 1 for some of the columns; see Table A.1 in the appendix for all the columns.

…where “Table 1” doesn’t contain a chapter number like “Table 1.1”, and where “Table A.1” uses some sort of prefix and restarts at 1.

I've played with two different approaches to get this to work:

1. Use a single .qmd file and add {.appendix} to headings
2. Use a Quarto book and use the appendices section

Neither works 100% consistently across all formats though. The single .qmd + {.appendix} approach works perfectly for PDFs but has issues with cross-reference numbering in HTML. The book approach works perfectly for HTML but has issues with document structure in PDF.

Here are some reproducible examples of both approaches

Approach 1: Use a single .qmd file and add {.appendix} to headings

Quarto can create an automatic appendix section by adding the {.appendix} class to a heading. This moves the heading down the end of the document to a special section.

Here’s a reproducible example:

manuscript.qmd

---
title: "Article with appendix"
author:
- name: Jane Doe
  affiliation: Big State University
- name: John Smith
  affiliation: Liberal Arts College
abstract: |
  Lorem ipsum dolor sit amet.
date: 2023-03-01
toc: true
---

Here's the introduction. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.


# Theory

Totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.


# Methods and data

Sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.

## Data

See @tbl-letters for some of the columns; see @tbl-letters-full in the appendix for all the columns.

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Some letters {#tbl-letters}

## Modeling approach

$$
\hat{y} = \beta_0 + \beta_1 x_1 + \varepsilon
$$


# Results

## Plots

Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet.

## Model results

Consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.


# Conclusion

Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? 


# Appendix {.appendix}

## Full data

| Col1 | Col2 | Col3 | Col4 |
|------|------|------| -----|
| A    | B    | C    | D    |
| E    | F    | G    | H    |
| I    | J    | K    | L    |
| M    | N    | O    | P    |
| Q    | R    | S    | T    |
| U    | V    | W    | X    |
| Y    | Z    | -    | -    |

: All the letters {#tbl-letters-full}

It looks like this:

Data subsection in the manuscript:

Appendix section at the end:

Downsides and workarounds

The table in the appendix is numbered as Table 2 and there’s no way to get “Table A1” since numbering is sequential throughout the document.

It is possible to use the crossref: chapter option to force numbering to restart in each H1…

---
...
date: 2023-03-01
toc: true
crossref: 
  chapters: true
---

…but this restarts cross references for each section, resulting in output like this:

See Table 2.1 for some of the columns; see Table 5.1 in the appendix for all the columns.

In PDF output, it’s possible to work around the sequential numbering issue by including some LaTeX code to use the \appendix environment and restart numbering. If you add this right before the # Appendix section…

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

…the resulting PDF shows the text correctly and the appendix starts on a new page at the end!

See Table 1 for some of the columns; see Table A1 in the appendix for all the columns.

General summary

Using {.appendix} works great for PDF with some added LaTeX code. It almost works for HTML and Word, but there’s no way to get correctly-restarted cross-reference numbers.

Approach 2: Use a Quarto book and use the appendices section

Quarto books support parts and appendices and .qmd files can be included as appendices by using the book: appendices YAML key. Instead of writing an article in one .qmd file, the content can be spread across two .qmd files—one named index.qmd that contains the main article, and one named appendix.qmd (or whatever else) that contains the appendix.

Here’s a reproducible example with three separate files:

_quarto.yml

project:
  type: book

book:
  title: "Article with appendix"
  author:
  - name: Jane Doe
    affiliation: Big State University
  - name: John Smith
    affiliation: Liberal Arts College
  abstract: |
    Lorem ipsum dolor sit amet.
  date: 2023-03-01
  search: false
  
  chapters:
    - index.qmd
  appendices: 
    - appendix.qmd

format:
  html:
    number-sections: false
    shift-heading-level-by: 1

  pdf:
    number-sections: true
    keep-tex: true

index.qmd

---
title: "Actual article"
---

Here's the introduction. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.


# Theory

Totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.


# Methods and data

Sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.

## Data

See @tbl-letters for some of the columns; see @tbl-letters-full in the appendix for all the columns.

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Some letters {#tbl-letters}

## Modeling approach

$$
\hat{y} = \beta_0 + \beta_1 x_1 + \varepsilon
$$


# Results

## Plots

Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet.

## Model results

Consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.


# Conclusion

Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? 

appendix.qmd

# Full data

| Col1 | Col2 | Col3 | Col4 |
|------|------|------| -----|
| A    | B    | C    | D    |
| E    | F    | G    | H    |
| I    | J    | K    | L    |
| M    | N    | O    | P    |
| Q    | R    | S    | T    |
| U    | V    | W    | X    |
| Y    | Z    | -    | -    |

: All the letters {#tbl-letters-full}

This works great for HTML output and creates a nice website structure for the article. The cross-reference numbering is also correct:

See Table 1 for some of the columns; see Table A.1 in the appendix for all the columns.

Downsides and workarounds

This gets a lot trickier with PDF output, though. Using the default documentclass: srcreport results in a PDF with a title page, an abstract page, a TOC page, and each H1 starting on its own page. The cross-reference numbering refers to chapter numbers:

See Table 2.1 for some of the columns; see Table A.1 in the appendix for all the columns.

The document structure is also off. The TOC shows a part-level entry for “Appendices”, but the “Actual article” entry for the overall article is a chapter-level entry, not a part.

Most of these issues can be cleaned up by:

• Switching to the article class
• Shifting heading levels back one level (since article doesn’t support \chapter{})
• Adding the manual \newpage + \appendix + cross-reference number resetting LaTeX code to the end of index.qmd (but not at the beginning of appendix.qmd, since Quarto moves the title of that document prior to any of its content)

format:
  pdf:
    documentclass: article
    number-sections: true
    shift-heading-level-by: 1
    keep-tex: true

This puts everything in an article-style document (with no chapters and no page breaks for each of the sections)…

…and it creates the correct cross-reference numbering:

See Table 1 for some of the columns; see Table A1 in the appendix for all the columns.

However, the TOC shows chapter-level entries for “Actual article” and “Appendices”. In a perfect world, it would be great if “Actual article” could be omitted entirely and “Full data” could go under “Appendices” as a subsection, but doing this seems like it would require some fancy LaTeX editing (perhaps with a Lua filter)

General summary

Using a Quarto book with separate .qmd files for the main manuscript and the appendix works great for HTML. It almost works perfectly for PDF with some added LaTeX code and some adjustments to heading levels and the document class, but hardcoded faux chapter titles are impossible to remove.

---

Ways to fix these issues?

Phew. With all that, does anyone know if there's a way to fix either of these issues?

1. For approach 1 (single file with {.appendix}): Is there a way to control cross-reference numbering in HTML output so that figures/tables/sections in the appendix can restart, resulting in text that would look like

   See Table 1 for some of the columns; see Table A.1 in the appendix for all the columns.

2. For approach 2 (book with index.qmd + appendix.qmd): Is there a way to have more control over the document structure in the TOC and not include the "Main article" heading as a chapter/section and include the appendix as a subsection under "Appendices" (or whatever the user specifies in language: en: section-title-appendices)?

[andrewheiss]

Ooh, here's a near-solution for approach two! Instead of using shift-heading-level-by: 1, if we use top-level-division: section, then "Appendices" gets a part-level entry in the TOC:

format:
  pdf:
    documentclass: article
    number-sections: true
    top-level-division: section

The only issue now is that section-level "1: Actual article" that isn't technically a heading but is showing up as one in the structure. If there were some way to omit it from the document (both in the TOC and in the document itself), it would be perfect.

[bcdavasconcelos]

Assuming that one is using the single .qmd file approach. Does the HTML output mean strictly a book-like single file or could it be made into a website as well?

[blenback]

Hi,
I have playing around with the single .qmd approach from @andrewheiss above to get alpha-numeric figure and table titles in appendices and I discovered a small improvement.

Using the LaTeX approach from above it will generate the correct output for the first appendix but the counter is not reset for subsequent Appendices. Also the 'A' in \renewcommand{\thefigure}{A\arabic{figure}} means every appendix will use this letter as a prefix.

---
title: "Appendix_repro"
format: pdf
editor: visual
linenumbers: false
numbersections: true
project:
  execute-dir: project
form: 
crossref:
  fig-title: Figure
  fig-prefix: Figure
  fig-labels: arabic
  appendix-title: "Appendix:"
  appendix-delim: ":"
  sec-prefix: ""
---

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

# 1st Appendix {.appendix}

| Col1 | Col2 | Col3 | Col4 |
|------|------|------| -----|
| A    | B    | C    | D    |
| E    | F    | G    | H    |
| I    | J    | K    | L    |
| M    | N    | O    | P    |
| Q    | R    | S    | T    |
| U    | V    | W    | X    |
| Y    | Z    | -    | -    |

: 1st Appendix table {#tbl-letters-full}


# 2nd Appendix {.appendix}

| Col1 | Col2 | Col3 | Col4 |
|------|------|------| -----|
| A    | B    | C    | D    |
| E    | F    | G    | H    |
| I    | J    | K    | L    |
| M    | N    | O    | P    |
| Q    | R    | S    | T    |
| U    | V    | W    | X    |
| Y    | Z    | -    | -    |

: 2nd Appendix table {#tbl-letters2-full}

A simple solution to this would be to repeat this LaTeX chunk at the start of each subsequent appendix to reset the counter and manually update the prefix but this is messy. A better solution I found is to use some additional LaTeX packages (included in the YAML below) and then include a LaTeX chunk at the start of the appendices as follows:

---
title: "Appendix_repro"
format: pdf
editor: visual
linenumbers: false
numbersections: true
project:
  execute-dir: project
form: 
crossref:
  fig-title: Figure
  fig-prefix: Figure
  fig-labels: arabic
  appendix-title: "Appendix:"
  appendix-delim: ":"
  sec-prefix: ""
header-includes:
- \usepackage[toc,title,page]{appendix}
- \usepackage{chngcntr}
---

```{=tex}
\appendix
\renewcommand{\thesection}{\Alph{section}}
\setcounter{section}{0}
\counterwithin{figure}{section}
\counterwithin{table}{section}
\begin{appendices}
```
# 1st Appendix {.appendix}

| Col1 | Col2 | Col3 | Col4 |
|------|------|------| -----|
| A    | B    | C    | D    |
| E    | F    | G    | H    |
| I    | J    | K    | L    |
| M    | N    | O    | P    |
| Q    | R    | S    | T    |
| U    | V    | W    | X    |
| Y    | Z    | -    | -    |

: 1st Appendix table {#tbl-letters-full}


# 2nd Appendix {.appendix}

| Col1 | Col2 | Col3 | Col4 |
|------|------|------| -----|
| A    | B    | C    | D    |
| E    | F    | G    | H    |
| I    | J    | K    | L    |
| M    | N    | O    | P    |
| Q    | R    | S    | T    |
| U    | V    | W    | X    |
| Y    | Z    | -    | -    |

: 2nd Appendix table {#tbl-letters2-full}

which gives the correct output and does not require additional chunks for subsequent appendices:

[andrewheiss]

In Quarto 1.4, it's now possible to define custom crossreferencable types, so you can make a specific kind for appendix images or appendix tables, like this:

---
title: "Testing"
crossref:
  custom:
    - kind: float
      prefix: Table A
      space-before-numbering: false
      name: Table A
      ref-type: apptbl
      latex-env: apptbl
      latex-list-of-file-extension: lost
      latex-list-of-description: Appendix Table
apptbl-cap-location: top
---


Here's the introduction. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.


# Theory

Totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.


# Methods and data

Sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.

## Data

See @tbl-letters for some of the columns; see @apptbl-letters-full in the appendix for all the columns.

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Some letters {#tbl-letters}

## Modeling approach

$$
\hat{y} = \beta_0 + \beta_1 x_1 + \varepsilon
$$


# Results

## Plots

Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet.

## Model results

Consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.


# Conclusion

Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? 


# Appendix {.appendix}

## Full data

::: {#apptbl-letters-full}

| Col1 | Col2 | Col3 | Col4 |
|------|------|------| -----|
| A    | B    | C    | D    |
| E    | F    | G    | H    |
| I    | J    | K    | L    |
| M    | N    | O    | P    |
| Q    | R    | S    | T    |
| U    | V    | W    | X    |
| Y    | Z    | -    | -    |

All the letters

:::

This creates a separate numbering system, so you get "Table 1" and "Table A1":

And the table caption is numbered correctly:

[acebulsk]

@cscheid I am having trouble getting the PDF output format to properly label the table.

For example:

---
title: "Testing"
format: pdf
crossref:
  custom:
    - kind: float
      reference-prefix: Table A
      space-before-numbering: false
      key: apptbl
      latex-env: apptbl
      latex-list-of-description: Appendix Table
apptbl-cap-location: top
---


Here's the introduction. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.


# Theory

Totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.


# Methods and data

Sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.

## Data

See @tbl-letters for some of the columns; see @apptbl-letters-full in the appendix for all the columns.

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Some letters {#tbl-letters}

## Modeling approach

$$
\hat{y} = \beta_0 + \beta_1 x_1 + \varepsilon
$$


# Results

## Plots

Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet.

## Model results

Consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.


# Conclusion

Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? 


# Appendix {.appendix}

## Full data

::: {#apptbl-letters-full}

| Col1 | Col2 | Col3 | Col4 |
|------|------|------| -----|
| A    | B    | C    | D    |
| E    | F    | G    | H    |
| I    | J    | K    | L    |
| M    | N    | O    | P    |
| Q    | R    | S    | T    |
| U    | V    | W    | X    |
| Y    | Z    | -    | -    |

All the letters

:::

Labels the appendix table as "Table 2" not "Table A1". Am I missing something?

[cscheid]

@acebulsk This is a quarto regression. Thanks for letting us know, we'll fix right away.

[cscheid]

@acebulsk We have a PR open that fixes this problem. You'll need to change your YAML a bit, though. Use this instead:

crossref:
  custom:
    - kind: float
      reference-prefix: Table A
      space-before-numbering: false
      key: apptbl
      latex-env: apptbl
      latex-list-of-description: Appendix Table
      caption-location: top

(That is, declare caption-location on the custom field.)

[acebulsk]

I tried your suggested YAML change and I am still getting Table 2 not Table A1. For now I've been able to get the desired result using the latex code originally suggested by OP:

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

[cscheid]

We have a PR open that fixes this problem

You need to wait for the PR to merge and a new release to be created...

[maia-sh]

Following on @andrewheiss' question, I tried to use Quarto 1.4's Custom Cross-Reference Types to reference entire Supplements (i.e., "For details, see Supplement 1. For information, see Supplement 2), rather than individual Tables or Figures. I aimed to also build on regular section referencing, i.e., sec-. Importantly, the supplements should have their own counter, distinct from the main manuscript. I also included the .appendix class for the supplement headers.

I have tried to no avail:

crossref:
  custom:
    - kind: float
      key: secsupp
      latex-env: secsupp
      reference-prefix: Supplement 
      space-before-numbering: true
      latex-list-of-description: Supplement

and

crossref:
  custom:
    - kind: float
      key: suppsec
      latex-env: suppsec
      reference-prefix: Supplement 
      space-before-numbering: true
      latex-list-of-description: Supplement

How might I use the new cross-ref features to accomplish this?

Many thanks for you help!

[mcanouil]

Could you share a small self-contained "working" (reproducible) example to work with of what you try to achieve? Thanks.
Only defining custom crossref is not enough, you also need to use it thus me asking an example.

You can share a Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).

````qmd
---
title: "Reproducible Quarto Document"
format: html
---

This is a reproducible Quarto document using `format: html`.
It is written in Markdown and contains embedded R code.
When you run the code, it will produce a plot.

```{r}
plot(cars)
```

![A placeholder image](https://placehold.co/600x400.png)

The end.
````

[maia-sh]

Thanks for the quick response @mcanouil. Here's my attempt at a reprex (which I always find tricky for quarto/rmd, so please excuse if it's not actually "reproducible"). I have split my main qmd and appendix qmd, which would be my preference and works fine for supplemental tables with Quarto 1.4.

---
title: "My Paper"
format: html
---

To keep this paper short, see @suppsec-details for more details.
For even more information, see @suppsec-information.

# Supplements
{{< include supplements.qmd >}}

---
title: "Supplements"
format: html
crossref:
  custom:
    - kind: float
      key: suppsec
      latex-env: suppsec
      reference-prefix: Supplement
      space-before-numbering: true
      latex-list-of-description: Supplement
---

# Details {#suppsec-details .appendix}

Here are fascinating tidbits.

# Information {#suppsec-information .appendix}

Even more fascinating tidbits!

[mcanouil]

I don't think the current custom cross-reference syntax supports sections right now. (cc @cscheid)

The following won't work, because the custom cross-reference is a heading attribute and not a cross-reference div.

---
title: "My Paper"
format: html
crossref:
  custom:
    - kind: float
      key: suppsec
      reference-prefix: Supplement
---

To keep this paper short, see @suppsec-details for more details.
For even more information, see @suppsec-information.

## Details {#suppsec-details .appendix}

Here are fascinating tidbits.

## Information {#suppsec-information .appendix}

Even more fascinating tidbits!

[mcanouil]

I've opened an issue to track this improvement:

• Sections/Parts custom cross-reference #8080

[iagopinal]

Take a look at figure-table-formatter. It moves the tables, figures, and supplements to wherever you indicate. You can cross-reference the figures and tables in the order that they are mentioned in the text, and sort them accordingly. It automatically outputs a file with the sorted tags of the figures and tables. You can use this file to automatically sort the figures in other files using the same filter (handy for supplements).

It would be nice to have the same functionality in the native Quarto, but at least this is a viable alternative now.

[oena]

Wanted to check in if there are any updates for this, specifically for rendering to Word documents--the examples above work for resetting PDF section numbering to begin with A (eg. A1, A1.1, etc) but I'm not sure how to do that for Word. Anyone have thoughts?

[mcanouil]

It would require to insert raw OpenXML code. But Word uses both static and dynamic components so not sure if this can be statically set.
Or changing the styling of the template document.
I don't recall how numbering is set for docx and afk at the moment.