tools-only Shortcodes
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 titlestart- Start time in secondswidth/height- Dimensionsaspect-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.
Meta
Access document metadata:
The title is: {{< meta title >}}
Author: {{< meta author >}}
Nested Metadata
{{< meta format.html.theme >}}
In Code Blocks
Works in code blocks too:
```yaml
title: { { < meta title > } }
```
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 >}}.
Contents
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 >}}