Add list of child documents in `_quarto.yml`

[ElsLommelen]

• for use of child documents in a website, I developed code to replace a specific text in a quarto.yml template with titles for a TOC and references to the corresponding .qmd child documents (see code starting here). It seems to work fine except for the fact that the preview is not running well after rendering due to this reported issue. Would it be an idea to add this as a separate function? Please let me know if you want me to contribute in this.

I agree it cwould be nice to have this as a separate function. I’d also like to think about how it would integrate with the other autoqmd functions in terms of naming and documentation. Also if you have a basic example to use in the unit tests, please let me know.

Originally posted by @wlangera in #7 (comment)

[ElsLommelen]

Eh, I'm afraid the website is not a basic example as data are needed for this, so I would advise using the iris child documents you are using already. For the _quarto.yml template, I started with generating a flandersqmd book and made some changes to make it a website (feel free to copy and simplify mine, you don't need >10 chapters, and use the iris species as childs). The most important for testing is that everything stays the same, except for

• this line that should be replaced by a list of all child chapters, e.g. (I cut a bit in it to make it not too long)

...
sidebar:
    contents:
      - wat.md
      - ...
      - section: "Bosreservaten in cijfers"
        href: cijfers.md
        contents:
          - text: Bos Ter Rijst
            file: fiches_reservaat_qmd/bos_terrijst.qmd
          - text: De heide
            file: fiches_reservaat_qmd/de_heide.qmd
          - text: Bos t'Ename
            file: fiches_reservaat_qmd/ename.qmd
          - text: Everzwijnbad
            file: fiches_reservaat_qmd/everzwijnbad.qmd
          - text: Withoefse heide
            file: fiches_reservaat_qmd/withoefse_heide.qmd
          - text: Zwaenepoel
            file: fiches_reservaat_qmd/zwaenepoel.qmd
      - meer.md
      - abstract.md
      - referenties.md
      - text: About
        file: colophon.md

• the message to be added in the beginning of the document

There is one difficulty: while I start from the file _quarto_template.yml and _quarto.yml is generated, there has to be a file called _quarto.yml before rendering with the button 'Render Website' (otherwise an error is dropped). It can be overwritten by a new version during pre-render, but the user should keep in mind that a file with this name should always be present. (And there is also the bug with the preview when changing this file, which hopefully will be solved.) So it is important to emphasise this in the documentation.
This might especially be a problem when ignoring this automatically produced _quarto.yml when pushing to GitHub, because the website won't build after downloading from GitHub. So maybe ignoring this file is not the best idea in this specific case?

[wlangera]

I think I do not want a separate function for this, but use the current autoqmd_* functions.

1. autoqmd_generate_children
   • creates child files (e.g. per species/reserve ...)
   • same use for both report/book/website
2. autoqmd_insert_includes
   • if qmd_file argument is a .qmd file --> use current implementation
   • if qmd_file argument is a .yml file --> use implementation of ElsLommelen

That way we keep the current workflow and we keep everything compact (limited number of functions).
If we do this we might want to change the name of autoqmd_insert_includes and its arguments (e.g. qmd_file -> file)
We would also need an extra argument for labels to use in the _quarto.yml.

[wlangera]

@ElsLommelen please try this:

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

_quarto.yml:

...
  sidebar:
    contents:
      - wat.md
      - nietsdoen.md
      - juridisch.md
      - reservaten.qmd
      - onderzoek.md
      - internationaal.md
      - section: "Bosreservaten in cijfers"
        href: cijfers.md
        contents:
        # AUTOGENERATED-START

        # Navigation entries are autogenerated. Do not edit manually.

        # AUTOGENERATED-END
      - meer.md
      - abstract.md
      - referenties.md
      - text: About
        file: colophon.md
...

pre-render script:

update arguments to your case

library(flandersqmd)

my_species <- paste("Iris", levels(iris$Species))
labels <- gsub("\\s", ".", tolower(my_species))

# Generate child documents
out_files <- autoqmd_generate_children(
  species = my_species,
  label = labels,
  template = "_species_template.qmd",
  child_dir = "child_qmd",
  freeze = "label"
)

# Insert entries into the Quarto configuration
autoqmd_insert_includes(
  target_file  = "_quarto.yml",
  child_files  = out_files,
  child_labels = my_species,
  start_marker = "# AUTOGENERATED-START",
  end_marker   = "# AUTOGENERATED-END"
)

post-render script:

update arguments to your case

library(flandersqmd)

message = c(
  "",
  "# Navigation entries are autogenerated. Do not edit manually."
)

# Clean report file and remove child files
autoqmd_finalise(
  target_files = "_quarto.yml",
  message = message,
  child_dirs_rm = "child_qmd",
  start_marker = "# AUTOGENERATED-START",
  end_marker   = "# AUTOGENERATED-END"
)