Include Not Expanded Here
Q-17-4 — Include Not Expanded Here
An include shortcode appears in a position where include expansion does not apply.
What this means
Quarto expands {{< include >}} shortcodes that stand alone: the
shortcode must be the sole content of its own paragraph, or of its
own line inside a fenced code block. This warning fires when an
include shortcode is written somewhere the expansion pass does not
reach — for example inline, in the middle of a sentence. The
shortcode is not expanded and contributes no content to the output.
Note the difference from Q-16-3 “Unknown Shortcode”: the name
include is recognized; the problem is the position, not the
spelling.
Why this happens
Common causes:
- An inline include —
some text {{< include _snippet.qmd >}} more text. Include expansion is block-level; it does not splice content into the middle of a paragraph. - Missing blank lines around the shortcode, causing it to be parsed as part of an adjacent paragraph instead of standing alone.
- An include sharing its line with code, inside a fenced code
block —
x = 1 {{< include app.py >}}. Inside a fence the shortcode must occupy a line of its own.
Includes nested inside containers — fenced divs, callouts, blockquotes, list items, tables — are expanded. So is an include alone on its own line inside a fenced code block, which embeds the target file’s text as a listing:
```{.python filename="app.py"}
{{< include app.py >}}
```Only the inline position, and a shortcode sharing its line with other content, are unsupported.
How to fix
Put the include shortcode in its own paragraph, surrounded by blank lines:
Some text before the include.
{{< include _snippet.qmd >}}
Some text after the include.