Subdocuments

When referring to a Quarkdown document, we're talking broadly about the group of resources that make up a Quarkdown project.

Commonly, especially in the case of knowledge management and wikis, pages can have links that point to other pages, building a network of interconnected subdocuments.

In Quarkdown, a subdocument's entry point is a source file that is referenced by another subdocument.
In practice, when I do this, I'm referring to a subdocument.

Every project consists of at least one subdocument: the main one, called root.

 

Note

Do not confuse subdocuments with inclusion: see Inclusion vs. subdocuments for a comparison.

 

Referencing subdocuments

Whenever a Markdown link points to a local .qd or .md file, it is considered a reference to a subdocument.

[My subdocument](file.qd)

Quarkdown makes sure a file is evaluated only once, hence circular and recursive references are handled gracefully.

 

Context inheritance

When referencing a subdocument, its content is evaluated like an independent Quarkdown document.

A relevant difference is that subdocuments inherit the referrer's context: document metadata, customizations, functions, variables and more.

main.qd:

.doctype {paged}
.theme {darko}
.pageformat margin:{1cm}

.function {greet}
    Hello!

[Introduction](introduction.qd)

introduction.qd:

No need to set the document up again, it's already inherited!

.greet

 

Contrary to .include, the context is inherited, not shared: changes made in the subdocument do not affect the referrer.

main.qd:

[Introduction](introduction.qd)

.greet <!-- Error: unresolved -->

introduction.qd:

.function {greet}
    Hello!

 

Working directory

The working directory of a subdocument is relative to the subdocument's entry point, not the referrer:

main.qd
pages/
| introduction.qd
images/
| image.png

Whereas main.qd can reference images/image.png, introduction.qd should reference it as ../images/image.png.

The media storage system can still store media files across subdocuments.

 

Subdocument graph

Subdocuments are structured in a directed graph, where the edges are the links between them.

The graph can be visualized via the .subdocumentgraph function:

 

Output

Subdocuments are exported differently depending on the output target.

HTML

Each subdocument is exported as a separate HTML file lying flatly in the same directory as index.html.

Configuration resources, such as themes and runtime scripts, are generated only once.

MyDocument/
| media/
| theme/
| script/
| index.html
| introduction.html
| conclusion.html

PDF

Each subdocument is exported as a separate PDF file.

MyDocument/
| index.pdf
| introduction.pdf
| conclusion.pdf

Important

Subdocument links in PDF output are not navigable.

In case only the root subdocument is present, then only MyDocument.pdf is generated without the need for a directory.

Minimizing name collisions

Since the subdocument output files lie flatly in the same directory, it's possible that two subdocuments with the same name but from different directories end up colliding.

By default, Quarkdown accepts this collision-prone behavior in order to generate human-readable URLs.

In case collisions cannot be avoided, launching the compiler with the --no-subdoc-collisions flag will append a hash to the output file names.