Creating Formats

Overview

Quarto format extensions enable you to add new formats to the built-in formats (e.g. html, pdf, docx) already available. Custom formats can provide default document options, style-heets, header, footer, or logo elements, and even bundle other extensions like filters and shortcodes. They are a great way to provide a common baseline for authoring documents or presentations within an organization, for a particular type of project or analysis, or for a specific publication.

You can specify a custom format beneath the format key just like a built-in format. For example:

----
title: "My Document"
format:
   acm-pdf: 
     toc: true
---

Custom formats all derive from one of the base formats, and include that base format as a suffix. Formats can also provide multiple variations that derive from distinct base formats. For example:

----
title: "My Document"
toc: true
format:
   acm-pdf: default
   acm-html: default
---

Note that we moved the toc option to the top level since it is shared between both of the formats.

Custom formats can also be used with the --to argument to quarto render. For example:

quarto render document.qmd --to acm-html

Next, we’ll walk through the creation of a custom format that extends the revealjs presentation format. If you are specifically interested in using or creating custom formats for journals and manuscripts, you may want to proceed instead to the documentation on Journal Articles.

Format Components

Custom formats are a type of Quarto Extension and creating a format works much like creating a filter or shortcode extension. We’ll walk through a custom format that extends the built-in revealjs format as an example. We’ll call our format lexconf. Here is what the source code repository of the format extension might look like:

README.md
LICENSE
template.qmd
_extensions/
  lexconf/
    _extension.yml
    theme.scss
    logo.png
    title.png

Note that the format suffix (revealjs) is excluded from the directory name (this is to account for the possibility of multiple formats e.g. lexconf-revealjs, lexconf-pptx, etc.)

As with other types of extensions, the only thing strictly required is the _extensions directory (anything above that is for your own purposes and is ignored during format installation). Even so, it’s good practice to include a README.md and LICENSE file. The template.qmd file serves a couple of purposes:

It can be rendered as you develop your format to ensure that things work as expected.
It can serve as the basis for a format template (which helps users gets started with using your format).

Here is what the contents of _extension.yml might look like:

title: LexConf 2022 Presentation
author: LexCorp
version: 1.0.0
contributes:
  formats:
    revealjs:
       theme: [default, theme.scss]
       logo: logo.png
       footer: | 
         Copyright 2022 (c) LexCorp, Inc.
       title-slide-attributes:
          data-background-image: title.png
          data-background-size: contain
       preview-links: auto

This format mostly provides organization-level content and theming. As mentioned above, formats can also include filters which allow for adding custom markdown constructs and rendering behavior.

Here is what the contents of template.qmd might look like:

---
title: "Presentation"
subtitle: "LexConf 2022"
author: "Your Name"
date: today
format: lexconf-revealjs
---

# Overview

Extension repositories are structured in such a way that you can test your extension and the template by simply rendering the template.qmd file right in the root of your repository. The template.qmd will be able to load your extension just as it would when installed, so testing and iterating should be as simple as working within your extension directory until you’re satisfied (without the need to repeatedly install or update the extension in order to test it).

Format Templates

Above we described including a template.qmd alongside your extension and then installing the template and format together with:

quarto use template <gh-organization>/<extension>

The template.qmd should demonstrate the functionality of the format and serve as a sound starting point for the user. When the extension template is copied into the target directory, the template.qmd will automatically be renamed to match the name that the user provided for the directory.

You can also include other files alongside template.qmd and they will be copied as well. Note that by default, Quarto will exclude common Github repository files when copying an extension template. This includes any file name or directory starting with a . (e.g. .gitignore), README.md, LICENSE, etc.. If you’d like, you can place a .quartoignore file in the root of your repository with each line of the file being a glob describing file(s) to ignore (using syntax like a .gitignore file).

Distributing Formats

You can distribute format extensions in one of two ways:

As a template that includes both the format in the _extensions directory and the template.qmd (which is automatically renamed to match the name of the enclosing directory).
As a plain format with no template scaffolding (this is useful for adding the format to an existing document or project).

If you have a GitHub repository containing the files enumerated above in the lexconf example, users could install your extension and associated template as follows (where lexcorp is the GitHub organization hosting the repo):

quarto use template lexcorp/lexconf

This is often the preferred way to get started with a format as it provides the user with a working document right out of the box. It’s also possible to install only the format if you working with an existing project:

quarto install extension lexcorp/lexconf

Note that it is possible to bundle and distribute extensions as simple gzip archives (as opposed to using a GitHub repository as described above). See the article on Distributing Extensions for additional details.

Common Metadata

If you have metadata that is common to any output format when your format extension is targeted, you can place that metadata under the common key. For example:

contributes:
  format:
    common:
      filters:
        - filter.lua
      shortcodes:
        - quarto-ext/fancy-text
    html:
      # html-speicific
    pdf:
      # pdf-specifc

Format Resources

You can easily include other files and resources within a format extension by placing those files within the extension directory and using relative paths to reference them. These relative paths will be properly handled.

If there are resources that you need to have copied to the input directory as a part of rendering the document (for example, a bst file for LaTeX bibliographies or a logo or other file referenced from a LaTeX template), you can provide format-resources, which is a list of file paths. Each of these files will be copied into the directory containing the input that is being rendered when the document is rendered. For example:

contributes:
  format:
    format-resources:
       - plos2015.bst

Extension Embedding

In some cases format extensions will want to make use of other extensions. This is permitted, but installing extensions for use within a custom format must be done with a special command line flag to ensure they are embedded correctly.

For example, here we want to make the fancy-text extension (which provides special formatting for the words $L A T E X$ and BibT_EX) available for users of the jss custom format:

quarto install extension quarto-ext/fancy-text --embed quarto-journals/jss

This will install the quarto-ext/fancy-text extension into the quarto-journals/jss extension in the _extensions folder. By embedding an extension you make it available without creating the potential for conflict with other versions of the extension that uses might already have installed.