Includes
Overview
Includes are a convenient way to re-use content across documents. Includes work for plain markdown content as well as for .qmd
files with executable code cells (note however that the cells must all use the same engine – i.e. knitr or jupyter, but not both).
To include a file, add the {{< include >}}
shortcode at the location in your document where you want it included.
{{< include _content.qmd >}}
Include shortcodes are equivalent to copying and pasting the text from the included file into the main file. This means that relative references (links, images, etc.) inside the included file resolve based on the directory of the main file not the included file.
Include shortcodes need to appear by themselves in a line, and they need to be surrounded by empty lines. This means that you cannot use an include shortcode inside markdown syntax (such as an item in a bulleted list).
Content
A concrete example would be if you have several articles about a topic that share a common introduction. Here we have an article titled “Revealjs Presentations” that wants to include some basic information on presentations not specific to Revealjs (we do that by including _basics.qmd
):
---
title: "Revealjs Presentations"
---
## Overview
Revealjs Presentations are a great way to
present your ideas to others!
{{< include _basics.qmd >}}
## Revealjs Options
More content here...
Note that we use an underscore (_
) prefix for the included file. You should always use an underscore prefix with included files so that they are automatically ignored (i.e. not treated as standalone files) by a quarto render
of a project).
Computations
You can also include files with computational cells. For example, here we include a .qmd
that does some data preprocessing that we want shared across multiple documents:
---
title: "My Document"
---
{{< include _data.qmd >}}
Use the data...
A couple of important things to remember when using computational includes:
All computations still share a single engine (e.g. knitr or jupyter)
Computational includes work only in
.qmd
files (they don’t work in.ipynb
notebook files)