/
On this page
Inclusion vs subdocuments
Quarkdown offers two ways to include content from other files: inclusion and subdocumenting. These approaches differ significantly in how they work and what they are best suited for.
Inclusion
Inclusion via .include and .includeall evaluates other Quarkdown source files.
The function returns the evaluation result, making it appear as if the target file’s content was inserted directly in place of the function call. This is an opaque operation because the output contains no traces of the original file.
Example 1
main.qd:Hello 1 .include {other.qd}
other.qd:Hello 2
index.html:
<p>Hello 1</p>
<p>Hello 2</p>Context
The execution context is shared between the main file and the included file.
Any customization, function, variable, and other information declared in the main file will be available in the included file, and vice versa.
You can optionally restrict this behavior via the sandbox parameter.
Circular references
Circular or recursive inclusions are not allowed and will result in an error.
Subdocuments
Subdocuments are independent and referenceable source files.
Subdocuments render as separate resources, and Quarkdown stores links to them in a graph structure.
Example 2
main.qd:Hello 1 [Other](other.qd)
other.qd:Hello 2
index.html:
<p>Hello 1</p>
<p><a href="./other">Other</a></p>other.html:
<p>Hello 2</p>Context
When evaluating subdocuments, the context is inherited from the referrer.
Any customization and declaration made in the referrer will be available in the subdocument, but not the other way around.
Circular references
Each subdocument is evaluated only once, so circular and recursive references are allowed.