Extension Types

Extensions

Quarto extensions add custom functionality including shortcodes, filters, formats, and RevealJS plugins.

Extension Types

Finding Extensions

Official Repository

• Quarto Extensions
• Browse by category: filters, shortcodes, formats, etc.

Community Extensions

• Community Extensions List
• Extensions JSON
• Search GitHub for quarto-extension

Installing Extensions

Basic Installation

quarto add username/repository

From GitHub

quarto add quarto-ext/fontawesome
quarto add shafayetShafee/bsicons

Specific Version

quarto add username/repository@v1.0.0

From URL

quarto add https://github.com/user/repo/archive/main.zip

Interactive Installation

When prompted, confirm trust in the extension source.

Using Extensions

In Document YAML

---
filters:
  - extension-name
---

Shortcode Extensions

After installing, use in document:

{{< fa brands github >}} # Font Awesome icon

Format Extensions

format: custom-format

Managing Extensions

Location

Extensions are stored in _extensions/ directory:

project/
├── _extensions/
│   └── fontawesome/
│       ├── _extension.yml
│       └── fontawesome.lua
├── document.qmd
└── _quarto.yml

List Installed Extensions

ls _extensions/

Update Extensions

quarto add username/repository  # Re-run to update

Remove Extensions

Delete the folder from _extensions/:

rm -rf _extensions/extension-name

Project vs Document Extensions

Project-Wide

Install in project root. Available to all documents:

project/
├── _extensions/
├── chapter1.qmd
└── chapter2.qmd

Global Extensions

Install in user config (less common):

quarto add --global username/repository

Location: ~/.local/share/quarto/extensions/

Popular Extensions

Icons

quarto add quarto-ext/fontawesome

{{< fa brands github >}} GitHub
{{< fa solid envelope >}} Email

Lightbox

quarto add quarto-ext/lightbox

lightbox: true

Include Code from Files

quarto add quarto-ext/include-code-files

{{< include-code example.py >}}

Fancy Text

quarto add quarto-ext/fancy-text

{{< lipsum 1 >}}

Social Cards

quarto add gadenbuie/quarto-social-embeds

{{< tweet user=username id=123456789 >}}

Extension Configuration

Some extensions have configuration options:

lightbox:
  match: auto
  effect: zoom
  loop: true

fontawesome:
  version: 6

Creating Custom Extensions

Basic Structure

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

Extension YAML

In _extension.yml:

title: My Extension
author: Your Name
version: 1.0.0
contributes:
  shortcodes:
    - my-extension.lua

Shortcode Lua

In my-extension.lua:

return {
  ['my-shortcode'] = function(args)
    local text = args[1] or "default"
    return pandoc.Str("Processed: " .. text)
  end
}

Use

{{< my-shortcode "Hello" >}}

Troubleshooting

Extension Not Found

ERROR: Extension not found

• Check extension is in _extensions/
• Verify extension name matches folder

Trust Warning

When installing, Quarto asks about trust. Extensions run code during render.

Conflicts

If extensions conflict, try:

1. Check extension documentation for compatibility
2. Update extensions to latest versions
3. Report issue to extension maintainer

Extension Sources

GitHub Organizations

• quarto-ext - Official Quarto extensions
• quarto-journals - Academic journal formats

Popular Repositories

Best Practices

Before Installing

1. Check extension source is trustworthy
2. Read the documentation
3. Check compatibility with your Quarto version

In Projects

1. Document which extensions are used
2. Include _extensions/ in version control
3. Pin versions for reproducibility

Updating

1. Test updates in development first
2. Check changelogs for breaking changes
3. Update one at a time

Resources

• Quarto Extensions Guide
• Creating Extensions
• Community Extensions
• Extensions JSON API