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 >}}

Important

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.

Important

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)