External

Quarto Extension

Author

{{< external https://raw.githubusercontent.com/mcanouil/quarto-external/refs/heads/main/README.md#installation >}}

{{< external https://raw.githubusercontent.com/mcanouil/quarto-external/refs/heads/main/README.md#usage >}}

{{< external https://raw.githubusercontent.com/mcanouil/quarto-external/refs/heads/main/README.md#example >}}

Installation

quarto add mcanouil/quarto-external@1.7.0

This will install the extension under the _extensions subdirectory.

If you’re using version control, you will want to check in this directory.

Usage

To use the external extension, you can include external content, a specific section, or a div from a file into your Quarto document using the external shortcode.

Basic syntax

Include the entire file:

{{< external <URI> >}}

Include a specific section (by header ID):

{{< external <URI>#<section-id> >}}

Include a specific div (by div ID):

{{< external <URI>#<div-id> >}}

<URI> specifies the location of the external file. This can be a local file path (outside the project directory) or a URL.

When using #<id>, the extension will first look for a header with that ID. If no header is found, it will then search for a div with that ID.

[!IMPORTANT] The external shortcode must be placed on its own line with no other content. Include blank lines both before and after the shortcode.

No code cells will or can be executed from the included file.

Currently supports .md, .markdown, and .qmd files only.

.md and .markdown files are included as-is.

.qmd files are processed as Quarto documents, so you can use Quarto features like citations, cross-references, and math.

Note: Using external content breaks the fully reproducible and self-contained nature of Quarto projects, as documents become dependent on external sources that may change or become unavailable.

Shifting heading levels

You can adjust the heading levels of included content using the shift-heading-level-by parameter (or the shorter shift alias):

{{< external <URI> shift-heading-level-by=1 >}}
{{< external <URI>#<section-id> shift=1 >}}

Positive values demote headings: shift=1 turns h1 into h2, h2 into h3, etc.
Negative values promote headings: shift=-1 turns h2 into h1, h3 into h2, etc.
Headings that would become level 0 or lower are converted to bold paragraphs.
Headings cannot exceed level 6 (capped).
Shift magnitudes greater than 5 produce a warning, since they always saturate.

This is useful when including content from a standalone document (with its own h1) into a section of your document.

Including by line range

Append #L<start>-<end> (or #L<n> for a single line) to the URI to include just a slice of the file:

{{< external path/to/file.qmd#L10-20 >}}
{{< external path/to/file.qmd#L42 >}}

The slice is taken from the raw file (before parsing), so line numbers correspond to what you see in your editor.

Dedenting included code blocks

Pass dedent=true to strip the longest common leading whitespace from every code block in the included content:

{{< external path/to/file.qmd#example dedent=true >}}

This is useful when the source code is indented inside a list item or a div in the original file.

Caching

Each unique URI is fetched at most once per render. Including the same file in multiple shortcodes (different sections, line ranges, or divs) does not re-download or re-read it.

Example

Here is the source code for a minimal example: example.qmd.

Output of example.qmd:

HTML

Shift Heading Level

The following includes the “Installation” section with headings shifted by +1 (demoted):

{{< external https://raw.githubusercontent.com/mcanouil/quarto-external/refs/heads/main/README.md#installation shift-heading-level-by=1 >}}

Installation

quarto add mcanouil/quarto-external@1.7.0

This will install the extension under the _extensions subdirectory.

If you’re using version control, you will want to check in this directory.

Include a Div

Source: https://github.com/mcanouil/quarto-extensions/blob/main/about.qmd

What is this?

This is a listing of {{< iconify simple-icons:quarto title='Quarto Logo' label='Quarto Logo' >}} Quarto extensions using {{< iconify octicon:mark-github-16 title='GitHub Logo' label='GitHub Logo' >}} GitHub API to retrieve information from the repositories.

Use with Quarto Wizard

Quarto Wizard is a Visual Studio Code extension/Positron/Codium that helps you manage your {{< iconify simple-icons:quarto title='Quarto Logo' label='Quarto Logo' >}} Quarto projects.
It allows you to easily install Quarto extensions directly from the Quarto Extensions listing repository.
This extension provides a user-friendly interface to browse, select, and install Quarto extensions, enhancing your Quarto development experience.

Include by Line Range

You can include a slice of a file using #L<start>-<end> (or #L<n> for a single line).

{{< external examples/snippet.qmd#L7-7 >}}

A short paragraph in the first section.

Dedent Included Code

Pass dedent=true to strip the longest common indent from every included code block. The code below comes from the snippet file with dedent=true:

{{< external examples/snippet.qmd#first dedent=true >}}

First section

A short paragraph in the first section.

def greet(name):
    print(f"Hello, {name}")

Repeated Includes Are Cached

The same URI is fetched once per render, even when referenced multiple times.

{{< external examples/snippet.qmd#second >}}
{{< external examples/snippet.qmd#second-div >}}

Second section

Another short paragraph.

Content inside a div in a .qmd snippet.