External

Include markdown from another file, or from a URL.

What the external extension is for, how to install it, and the smallest shortcode that pulls content in.
Author

Mickaël CANOUIL, Ph.D.

Some prose belongs in more than one document: an installation section shared by a README and a website, a changelog written once and shown twice, a snippet that lives in a file outside the project. Copying it means keeping the copies in step, and forgetting to.

external includes it instead. Point the shortcode at a file or a URL and its content is parsed and dropped in, whole or by the section, div, or line range you name.

Installation

quarto add mcanouil/quarto-external@1.7.1

This will install the extension under the _extensions subdirectory. If you are using version control, you will want to check in this directory.

Or install it from your editor with Quarto Wizard:

Visual Studio Code Positron VSCodium

Quick start

The whole file:

{{< external notes.qmd >}}

One section of it, by the identifier of its heading:

{{< external notes.qmd#release-notes >}}

A slice of it, by line number:

{{< external notes.qmd#L10-20 >}}
Important

The shortcode has to sit on a line of its own, with a blank line above and below. It produces blocks rather than inline content, and Quarto will not place it correctly otherwise.

See the Reference for every option, and the Examples for each of them rendered.

Where it works

Every output format. The content is parsed into the document before any writer runs, so what you include behaves like anything you typed.

Warning

Including content from outside the project trades reproducibility for reuse. A document that reads a URL is only as stable as that URL, and no longer builds the same way offline or a year from now.

Code cells in the included file are not executed, in any format.

Back to top