A filter to auto-generate a code appendix in rendered Quarto documents

[cl-roberts]

Description

Overview

I recently made a lua filter called code-appendix that moves the display of code chunks when echo: true to an appendix at the end of rendered Quarto documents. It can also write the code chunks to a user-defined file as a side effect, if desired. I have so far tested it with pdf, typst, html and docx formats.

Use case

This filter is useful when you want to show the outputs of analysis code in a Quarto document but don't want the code chunks themselves displayed until the very end. Such a scenario might be a homework assignment, an analysis report to both technical and non-technical readers, or a blog post which focuses on analysis rather than code (i.e., not a tutorial).

An example

The traditional way to control the location of code chunks in the rendered .qmd (or .rmd) document is to use ref-label (when using knitr engine). For example, as discussed in #6650. An example of creating a code appendix using ref-label is:

---
echo: false
---

# Example

The code chunk generating the following output

```{r}
#| label: r-code

print("some r code")
```

gets moved to an appendix at the end of the document.

## Source code:

```{r}
#| echo: true
#| eval: false
#| ref-label: r-code
```

My code-appendix filter represents a simpler but less flexible tool to achieve the same goal. The same example above using the filter:

---
filters:
  - code-appendix
code-appendix-title: "Source code:"
code-appendix-header-level: 2
echo: true
---

# Example

The code chunk generating the following output

```{r}
print("some r code")
```

gets moved to an appendix at the end of the document.

Features

The default behavior of code-appendix is to stop the rendering of code chunks throughout the main body of the document and instead display them altogether in an appendix at the end. The title of the appendix can be controlled with YAML options.

As a side-effect, the filter can write the content of the code chunks to a file specified in the YAML. This is useful for two reasons:

1. A user can collect all analysis code used in a .qmd file into a working .r or .py script on rendering
2. A user can generate a standalone .qmd file containing the analysis code. This can be handy as it allows the user to make edits to the code appendix by hand and can then be included in the main document via the {{< include >}} shortcode.

[cderv]

Awesome ! Nice idea!

Could you open a PR in quarto-dev/quarto-web to list your extension in https://quarto.org/docs/extensions/ ?
See https://github.com/quarto-dev/quarto-web/blob/main/docs/extensions/listings/shortcodes-and-filters.yml

Thanks !

[cl-roberts]

Just submitted a PR

[mcanouil]

Thanks for sharing.

Feel free to submit your extension to: https://m.canouil.dev/quarto-extensions/about.html
Edit: in fact, multi extensions repositories are not supported as the different extensions would share the same metadata making it useless.

---

May I ask you to harmonise the code cell options to only use YAML syntax instead of mixing R inline and YAML syntaxes?

```{r}
#| echo: true
#| eval: false
#| ref-label: r-code
```

[cl-roberts]

Sure!

[cl-roberts]

Edit: in fact, multi extensions repositories are not supported as the different extensions would share the same metadata making it useless.

I just made a standalone repo for the filter and submitted it to quarto-extentions.