Using Extensions

Overview

Quarto Extensions are a powerful way to modify or extend the behavior of Quarto, and can be created and distributed by anyone. There are two types of extensions available:

  • Shortcodes are special markdown directives that generate various types of content. For example, you could create shortcodes to embed tweets or videos in a document.

  • Filters are a flexible and powerful tool for introducing new global behaviors and/or new markdown rendering behaviors. For example, you could create filters to implement output folding, an image carousel, or just about anything you can imagine!

  • Formats enable you to create new output formats by bundling together document options, templates, stylesheets, and other content.

Extensions are a recently released Quarto feature so you should be sure to install the very latest version of Quarto (at least v1.0.15) before proceeding.

Here are some examples of extensions developed and maintained by the core Quarto team:

Extension Description
lightbox Create lightbox treatments for images in your HTML documents.
code-filename Add a filename header to code blocks.
fancy-text Output nicely formatted versions of fancy strings such as LaTeX and BibTeX in multiple formats.
fontawesome Use Font Awesome icons in HTML and PDF documents.
grouped-tabsets Add grouped tabsets, which remember the active tab across multiple HTML documents.
latex-environment Quarto extension to output custom LaTeX environments.

This articles covers the basics of installing and using extensions. The articles on Creating Shortcodes and Creating Filters cover how to create your own extensions.

Extension Trust

It’s important to note that Quarto extensions may execute code when documents are rendered. If you do not trust the authors of an extension, we recommend that you do not install or use the extension.

Installation

If you want to use an extension within a document or project you need to install it. Rather than installing into a global library, Quarto extensions are installed locally, directly alongside the document or project they are used within. For example, if you have a project in a directory named myblog, you could install some extensions for use with that the project as follows:

cd myblog
quarto install extension quarto-ext/fontawesome
quarto install extension quarto-ext/grouped-tabsets

This will result in an _extensions folder being created at the root of your project, and the fontawesome and grouped-tabsets extensions being installed within it.

Note that a project isn’t strictly required for using extensions—if you install into a directory that isn’t a project then any document located directly alongside the _extensions folder can use the extensions.

Extensions and Version Control

If you are using version control you should check the _extensions directory in to your repo along with your other code. Installed extensions are treated as source code for your project to ensure very long term reproducibility—your project doesn’t need to rely on the availability of an external package manager (or the maintenance of older extension versions) to successfully render now and far into the future.

Repositories

These extensions in the example above were prefixed with quarto-ext because they were distributed from the quarto-ext GitHub organization. Extensions can be similarly distributed from any GitHub organization. So for example the following might also be valid extension installation commands:

quarto install extension cooltools/lightbox
quarto install extension bigstateu/fancytweet

While its convenient to distribute extensions using GitHub, you can also dstribute them as an ordinary gzip archive which can be installed from a URL or a local file. See the article on Distributing Extensions for additional details.

Managing Extensions

The are several commands available for listing, updating, and removing extensions:

quarto list extensions
quarto update extension quarto-ext/fontawesome
quarto remove extension quarto-ext/fontawesome

Note that when updating an extension you’ll be prompted to confirm the update based on the version you have and the version you are attempting to update to.

If you run the quarto remove extension command with no extension-id, you will be presented with a list of extensions that are installed and you may select which extensions to remove.

Using Shortcodes

Shortcodes are special markdown directives that generate various types of content. Quarto shortcodes are similar in form and function to Hugo shortcodes and WordPress shortcodes.

For example, the following shortcode prints the title from document metadata:

{{< meta title >}}

The meta shortcode is built-in to Quarto. Extensions can provide additional shortcodes. For example, the quarto-ext/fontawesome extension provides the fa shortcode which enables you to use icons from Font Awesome Free within HTML and PDF documents.

You can use the fa shortcode by first installing it:

quarto install extension quarto-ext/fontawesome

Then using it within a document as follows:

---
title: My Awesome Document
---

## Section

This document uses Font Awesome {{< fa smile >}}.

Using Filters

Filters provided by extensions need to be explicitly included in the list of filters used to render a document.

To use a filter extension, first install the extension using quarto install extension:

quarto install extension quarto-ext/latex-environments

Then, add the extension name to the list of filters for your document or project:

---
title: My Environments Document
format:
  pdf: default
filters:
  - latex-environments
environments: [program]
---

:::{.program}
The contents of this div will be output in a `program`
latex environment, but will appear in HTML (and any other output 
format as a simple div with the class `program`)
:::

Note that if you have installed two filters with the same name you can further qualify them using the organization name, for example:

filters:
  - quarto-ext/latex-environments

Learning More

Here are some possible steps for learning more about Quarto extensions:

  • The Quarto Extensions GitHub organization provides a set of extensions developed by the core Quarto team. Many of these extensions implement frequently requested features, and all of them provide sound examples of how to implement extensions.

  • Creating Shortcodes describes how to implement your own shortcode extensions.

  • Creating Filters describes how to implement your own filter extensions.

  • Developing with Lua helps you get started with Lua (the language used to create extensions) and provides documentation for Quarto Lua functions useful for extensions.

  • Distributing Extensions goes into more depth on how to package and distribute extensions, both on GitHub and using plain gzip archives.