How can I use child documents in Quarto?

[wlangera]

I would like to use child documents in a Quarto project, similar to how child documents can be used in Bookdown.

For example, suppose I have a report with one section per species, and I want each species section to be maintained as a separate .qmd file. Ideally, these child documents should be generated automatically from a template and included in the main Quarto document during rendering.

What is the recommended way to achieve this in Quarto?

[wlangera]

Quarto does not handle child documents in exactly the same way as Bookdown. In particular, it is better not to think of this as a loop inside a .qmd file. Instead, Quarto can compose multiple .qmd files using its {{< include >}} shortcode.

The flandersqmd development version provides autoqmd_*() helper functions that automate this workflow.

remotes::install_github("inbo/flandersqmd#7")

We are still fixing some small bugs and documentation files, but the main functions seem to work well.
We hope to merge this soon with the main package version.

The basic idea is:

1. Create a template .qmd file containing the structure of one child document.
2. Generate one child .qmd file per entity from this template.
3. Insert {{< include >}} directives for these child documents into the parent .qmd.
4. Let Quarto render the project normally.
5. Remove the generated child documents and restore the parent document after rendering.

This means that the generated child documents only exist temporarily during the rendering process. The source project can therefore remain clean and the generated files do not need to be manually maintained.

1. Create a template

For example, _species_template.qmd could contain:

### {{species}}

The results for *{{species}}* are shown below.

```{r}
# Analysis for this species
```

The template can contain ordinary Quarto content, code chunks, figures and cross-references. It is recommended to prefix the template with _, so Quarto does not treat it as a document to render independently.

2. Add markers to the parent document

In the parent document, add markers indicating where the generated child documents should be inserted:

## Results

<!-- AUTOGENERATED-START -->

> Content between these markers is automatically generated.
> Do not edit manually.

<!-- AUTOGENERATED-END -->

The autoqmd_*() functions will only modify the content between these markers.

3. Generate and insert the child documents

The simplest approach is to use autoqmd_prepare():

library(flandersqmd)

my_species <- paste("Iris", levels(iris$Species))

autoqmd_prepare(
  species = my_species,
  label = gsub("\\s", ".", tolower(my_species)),
  template = "_species_template.qmd",
  child_dir = "child_qmd",
  target_file = "iris_chapter.qmd"
)

This generates one .qmd file for each species and inserts the corresponding Quarto include directives into iris_chapter.qmd.

After the function runs, the relevant part of the parent document will look roughly like:

<!-- AUTOGENERATED-START -->

{{< include child_qmd/_qmd_02282edd.qmd >}}

{{< include child_qmd/_qmd_08a15729.qmd >}}

{{< include child_qmd/_qmd_08758dcd.qmd >}}

<!-- AUTOGENERATED-END -->

Quarto then renders these included .qmd files as part of the parent document.

4. Clean up after rendering

Because the child documents are generated files, they can be removed automatically after rendering using autoqmd_finalise():

library(flandersqmd)

autoqmd_finalise(
  target_files = "iris_chapter.qmd",
  child_dirs_rm = "child_qmd"
)

This removes the generated child documents and restores the parent document to its original state, with only the autogenerated markers remaining.

5. Automate this with Quarto pre- and post-render hooks

The generation and cleanup can be connected to Quarto's render lifecycle using a pre-render and post-render script:

project:
  type: book
  pre-render: pre_render.R
  post-render: post_render.R

The pre-render script calls autoqmd_prepare(), while the post-render script calls autoqmd_finalise().

This means that running

quarto render

is sufficient to generate, include and subsequently clean up all child documents.