Shortcodes

February 20, 2026 · View on GitHub

Shortcodes are special commands that expand into content at render time. Quarto provides several built-in shortcodes.

Syntax

Shortcodes use double curly braces with angle brackets:

{{< shortcode-name argument >}}

Or with named parameters:

{{< shortcode-name param="value" >}}

Video

Embed videos from various sources:

YouTube

{{< video https://www.youtube.com/embed/VIDEO_ID >}}

Or with just the ID:

{{< video https://youtu.be/VIDEO_ID >}}

Vimeo

{{< video https://vimeo.com/VIDEO_ID >}}

Local Video

{{< video video.mp4 >}}

Video Options

{{< video https://youtu.be/VIDEO_ID
title="Video Title"
start="30"
aspect-ratio="16x9"
width="100%"

> }}

Options:

title - Video title
start - Start time in seconds
width / height - Dimensions
aspect-ratio - 16x9, 4x3, 1x1, 21x9

Include

Include content from other files:

Basic Include

{{< include _content.qmd >}}

Include Section

Include only part of a file:

{{< include _content.qmd#section-id >}}

Include with Path

{{< include path/to/file.qmd >}}

Usage Notes

Included files are processed as Quarto markdown
Use _ prefix for files to exclude from rendering
Paths are relative to the including document

Embed

Embed output from Jupyter notebooks:

Embed Cell Output

{{< embed notebook.ipynb#cell-id >}}

Embed with Options

{{< embed notebook.ipynb#fig-plot echo=true >}}

Options:

echo - Show source code (true/false)

Finding Cell IDs

Cell IDs are set in notebook metadata or automatically generated.

Var

Access variables from _variables.yml:

Define Variables

Create _variables.yml:

version: 2.0.0
company: Acme Corp

Use Variables

Current version: {{< var version >}}
Published by {{< var company >}}.

Nested Variables

contact:
  email: info@example.com
  phone: 555-1234

Email: {{< var contact.email >}}

Env

Access environment variables:

Home directory: {{< env HOME >}}
User: {{< env USER >}}

Default Value

{{< env MY_VAR default="not set" >}}

Pagebreak

Insert a page break:

Content before.

{{< pagebreak >}}

Content after (on new page in PDF).

Works across formats (PDF, Word, HTML print).

Kbd

Describe keyboard shortcuts:

Press {{< kbd Ctrl+C >}} to copy.
Save with {{< kbd Cmd+S >}} on Mac.

Multiple Keys

{{< kbd Ctrl+Shift+P >}}
{{< kbd Cmd-Option-Esc >}}

Lipsum

Generate placeholder text:

{{< lipsum 1 >}}

Generates one paragraph of Lorem Ipsum.

Multiple Paragraphs

{{< lipsum 3 >}}

Placeholder

Generate placeholder images:

{{< placeholder 400 300 >}}

Creates a 400x300 placeholder image.

With Format

{{< placeholder 400 300 format=svg >}}

Version

Show Quarto version:

Built with Quarto {{< version >}}.

Rearrange document content:

{{< contents heading >}}

Shows content under a specific heading. Useful for reorganizing included content.

Conditional Shortcodes

Shortcodes can be format-specific:

::: {.content-visible when-format="html"}
{{< video video.mp4 >}}
:::

::: {.content-visible when-format="pdf"}
See video at: https://example.com/video
:::

Custom Shortcodes

Create custom shortcodes via extensions. Example extension structure:

_extensions/
└── my-shortcode/
    ├── _extension.yml
    └── my-shortcode.lua

Shortcodes in Code

Shortcodes work in inline code and code blocks:

`{{< meta title >}}`

version: {{< var version >}}

Escaping Shortcodes

To show shortcode syntax without executing:

{{{< shortcode >}}}`

Or use raw block:

```{.markdown shortcodes=false}
{{< shortcode >}}
```

Examples

Documentation Site

# {{< meta title >}} v{{< var version >}}

{{< include _installation.qmd >}}

## Video Tutorial

{{< video https://youtu.be/TUTORIAL_ID >}}

## Keyboard Shortcuts

- Copy: {{< kbd Ctrl+C >}}
- Paste: {{< kbd Ctrl+V >}}

{{< pagebreak >}}

## Appendix

{{< include _appendix.qmd >}}

Project Variables

_variables.yml:

product:
  name: "MyApp"
  version: "2.1.0"
  year: 2024

Document:

# {{< var product.name >}}

Version {{< var product.version >}} - Copyright {{< var product.year >}}