Examples
Each fragment form, rendered.
Everything below is included by the extension as this page is built, from sample files kept beside these pages in _examples/. The leading underscore keeps Quarto from rendering them as pages of their own. The missing-target and URL sections print their calls instead of running them, for the reasons given there.
The main sample is a small standalone document:
---
title: "A standalone document"
author: "Someone else"
---
# Release notes {#release-notes}
The first section of the sample file, with its own heading.
## Details {#details}
A subsection, with an identified div under it.
::: {#usage}
A div with an identifier, rather than a heading.
```r
x <- seq_len(10)
mean(x)
```
:::
# Upgrade notes {#upgrade-notes}
A second top-level section, so an example can shift a heading of its own.
## Breaking changes {#breaking-changes}
A subsection, so a shift has something to nest.The first examples pull different parts of it, and the later ones use further files in the same directory. Some of them pull the same content twice, and no identifier reaches this page twice, because extracting a div drops the wrapper that carries the identifier.
One section
Name the identifier of a heading, and you get that heading and everything under it.
{{< external _examples/sample.qmd#details >}}Details
A subsection, with an identified div under it.
A div with an identifier, rather than a heading.
x <- seq_len(10)
mean(x)One div
The same fragment syntax finds a div when no heading matches, and returns its contents.
{{< external _examples/sample.qmd#usage >}}A div with an identifier, rather than a heading.
x <- seq_len(10)
mean(x)The code block above keeps the indentation it had inside the div.
Dedenting
dedent=true strips the longest common leading whitespace from every code block in what is included.
{{< external _examples/sample.qmd#usage dedent=true >}}A div with an identifier, rather than a heading.
x <- seq_len(10)
mean(x)Shifting headings
The sample starts at level one. Included as it stands, its headings would sit above the ones on this page.
{{< external _examples/sample.qmd#upgrade-notes shift=3 >}}Upgrade notes
A second top-level section, so an example can shift a heading of its own.
Breaking changes
A subsection, so a shift has something to nest.
shift=3 moves the level one heading to level four and the level two heading to level five, so both sit under this section.
A line range
Line numbers are taken from the raw file, before parsing, so they match what an editor shows. A range does not have to line up with a section: here it is the fenced block on lines 18 to 21, and nothing else.
{{< external _examples/sample.qmd#L18-L21 >}} x <- seq_len(10)
mean(x)A .md file
A .md file is read by Pandoc, and any shortcode in it is escaped rather than run. The sample starts at level one, so shift=2 is here as well, to keep its heading below this one.
{{< external _examples/sample.md shift=2 >}}Plain markdown
A .md file is read by Pandoc, and any shortcode in it is escaped rather than run: {{{< meta title >}}} comes out as text.
The {{< meta title >}} in that file comes out as text. Had the same content been in a .qmd file, Quarto would have run it and printed this page’s title instead.
The whole file
Leave the fragment off, and the whole file comes across.
_examples/standalone.qmd is a second sample. It holds YAML front matter, a level one heading, and a level two heading under it.
{{< external _examples/standalone.qmd shift-heading-level-by=2 >}}Migration guide
A second sample file, so a whole-file example does not repeat an identifier from the first.
Deprecations
A subsection, so a whole-file include has two levels to move.
shift-heading-level-by is the full name of the attribute the earlier examples wrote as shift. Both names reach the same code, and Attributes gives the pair.
The front matter of that file reaches the parser, and the parser does not turn it into content, so none of it appears above.
One line
A fragment can name a single line as well as a range.
{{< external _examples/sample.qmd#L8 >}}The first section of the sample file, with its own heading.
Line 8 of the sample is the paragraph under its first heading. Fragments lists this form beside the range form.
Promoting headings
A negative value promotes instead of demoting. #nested-note in _examples/levels.qmd is a level four heading, so shift-heading-level-by=-1 lifts it to level three.
{{< external _examples/levels.qmd#nested-note shift-heading-level-by=-1 >}}Nested note
A level four heading, so an example can promote it to level three.
Past level one
A heading cannot rise above level one. #top-note in _examples/levels.qmd is a level one heading with a level two heading under it, and shift-heading-level-by=-2 puts both past that limit.
{{< external _examples/levels.qmd#top-note shift-heading-level-by=-2 >}}Top note
A section at level one, so an example can push a heading past level one.
Under the top note
A subsection, so one shift reaches two headings.
Each one arrives as a bold paragraph, as Shifting headings says it will. A bold paragraph carries no identifier, so neither #top-note nor #under-top-note reaches this page.
Paths inside the file
The extension moves heading levels when shift-heading-level-by asks it to, strips indentation when dedent is set, and always escapes the shortcodes in a .md file. It touches no link and no image, so a path arrives exactly as the file wrote it.
_examples/nested/note.md sits one directory below this page, and its link names reference.qmd.
{{< external _examples/nested/note.md >}}A file kept in _examples/nested/, one directory below the page that includes it.
Its link points at the reference page, written the way the including page would write it.
The link works because it is written as this page would write it, not as the file’s own directory would. Write every path in a file meant for inclusion the way the including page needs it.
When the target is missing
The two calls below are printed rather than run. One of them would stop this render, and the other would put an error in it.
A file that cannot be read stops the render:
{{< external _examples/absent.qmd >}}Quarto reports File '_examples/absent.qmd' not found in resource path, and no page is produced. Check the path before you commit the call.
A fragment that matches nothing is milder, and leaves the rest of the page alone:
{{< external _examples/sample.qmd#absent-section >}}The extension names the identifier it could not find, includes nothing, and the render finishes. A line range that starts past the end of the file behaves the same way. Validation lists each check.
A URL
The first argument can be a URL, and the file is fetched while the document renders.
{{< external https://raw.githubusercontent.com/mcanouil/quarto-external/main/example.qmd >}}That call is printed rather than run, on purpose. A rendered one would make this site’s own build wait on a network request. A target that moves or disappears then stops the build, as a missing local file does. Version the file with the project when you can. See Caching for what several calls on one URI cost.
Source
The repository ships a short, standalone starting point you can copy: example.qmd.