You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: vignettes/articles/autoqmd.qmd
+8-4Lines changed: 8 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,7 @@ Autogenerated child `.qmd` files are most useful when a report contains many sec
33
33
Compared to alternatives, this approach offers several advantages:
34
34
35
35
* Manual copy-paste does not scale and is prone to inconsistencies.
36
-
*Parameterised Quarto documents work well for generating multiple standalone reports, but are less suited for assembling many repeated sections within a single report or book.
36
+
*Parametrised Quarto documents work well for generating multiple standalone reports, but are less suited for assembling many repeated sections within a single report or book.
37
37
* Loops inside a single `.qmd` file can work for simple cases, but often lead to long, hard-to-read documents with complex chunk logic and limited control over section structure, chunk labels, and page breaks.
38
38
39
39
The `autoqmd_*()` approach trades a small amount of upfront structure for clearer separation of concerns: templates define what a section looks like, pre-render scripts define how many sections are needed, and Quarto handles where they appear in the final output.
@@ -83,10 +83,12 @@ Outside these markers, the document remains entirely under manual control.
83
83
84
84
### Step 2: Create template from which to make child documents
85
85
86
-
Next, define a template .qmd file that describes the structure of one repeated section. This template uses placeholder variables (e.g. `{{species}}` or `{{label}}`) that will be substituted during generation. The template can contain text, code chunks, figures, and cross-references, just like any other Quarto document.
86
+
Next, define a template `.qmd` file that describes the structure of one repeated section. This template uses placeholder variables (e.g. `{{species}}` or `{{label}}`) that will be substituted during generation. The template can contain text, code chunks, figures, and cross-references, just like any other Quarto document.
Each generated child document will be a fully valid `.qmd` file derived from this template. Template files are never rendered directly by Quarto; they are only used as blueprints for generating temporary child documents.
137
141
138
142
### Step 3: Create pre-render script
139
143
140
144
Child documents are created and inserted before rendering, using a pre-render script. This script is responsible for:
141
145
142
-
1. Generating one child .qmd file per entity (here: per species)
146
+
1. Generating one child `.qmd` file per entity (here: per species)
143
147
2. Inserting `{{< include >}}` directives between the markers in the main chapter
144
148
145
149
This can be done either explicitly or via a convenience wrapper.
@@ -188,7 +192,7 @@ autoqmd_prepare(
188
192
When the pre-render script is executed, the following things happen:
189
193
190
194
* The directory `child_qmd` is created (if needed)
191
-
* One temporary child .qmd file is generated per species
195
+
* One temporary child `.qmd` file is generated per species
192
196
* The main chapter is updated between the markers only
0 commit comments