Journal Formats

Overview

This article provides a guide to creating your own custom Journal formats. As a supplement to this guide we also recommend the following learning resources:

The source code for the Journal article formats available from the quarto-journals GitHub organization.
The GitHub template repository for creating new Journal formats. The code in the template repository is heavily annotated so creating a new repository using this template and experimenting with it is an excellent way to learn.

Journal custom formats can be used just like normal Quarto formats (e.g. pdf and html):

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:

Terminal

quarto render document.qmd --to acm-pdf

Quick Start

Here we’ll describe how to create a simple Journal article format extension. We’ll use the quarto create command to do this. If you are using VS Code or RStudio you should execute quarto create within their respective integrated Terminal panes.

To get started, execute quarto create extension journal within the parent directory where you’d like the format to be created:

Terminal

$ quarto create extension journal
 ? Extension Name › aps

As shown above, you’ll be prompted for an extension name. Type aps (an acronym for a fictional academic association) and press Enter—the Journal format extension is then created:

Creating extension at /Users/jjallaire/quarto/dev/aps:
  - Created README.md
  - Created template.qmd
  - Created _extensions/aps/aps.lua
  - Created _extensions/aps/styles.css
  - Created _extensions/aps/_extension.yml
  - Created _extensions/aps/header.tex
  - Created bibliography.bib

If you are running within VS Code or RStudio a new window will open with the extension project.

Here’s what the contents of the files in _extensions/aps/ look like:

_extensions/aps/_extension.yml

title: Aps
author: J.J. Allaire
version: 1.0.0
quarto-required: ">=1.2.222"
contributes:
  formats:
    common:
      toc: true
      filters:
        - aps.lua
    pdf:
      include-in-header: header.tex
    html:
      css: styles.css

The main _extension.yml config file defines the output formats available for this Journal. Here we defined pdf and html formats, which will be available to Quarto documents as aps-pdf and aps-html, respectively.

The config file also points to a number of other files that are used to customize the appearance of the Journal article:

header.tex — Custom LaTeX header directives
styles.css — Custom CSS for HTML output
aps.lua — Lua filter for various custom transformations

Finally, the template.qmd provides a base example article for users of the format:

template.qmd

---
title: Aps Template
format:
  aps-pdf:
    keep-tex: true  
  aps-html: default
author:
  - name: Sarah Malloc
    affiliations:
      - name: An Organization
        department: The Department
        address: 1 Main St
        city: Boston
        country: USA
        postal-code: 02210-1022
      - A second affiliation
    orcid: 0000-0000-0000-0000
    email: sm@example.org
    url: https://example.org/
  - name: Eliza Dealloc
    affiliations:
      - Another Affiliation
abstract: |
  This document is a template demonstrating the Aps format.
keywords: [template, demo]
bibliography: bibliography.bib  
---

## Introduction {#sec-intro}

*TODO* Create a template that demonstrates the appearance, formatting, layout, and functionality of your format. Learn more about journal formats at <https://quarto.org/docs/journals/>.

To develop your format, render/preview template.qmd, and then make changes to the various files in the _extensions directory (the preview will automatically refresh when you change these files).

Example: ACM Format

The Quick Start above creates a very simple Journal article format. Here we’ll walk through some of the code for a more complex example, the ACM Format available from quarto-journals.

Before proceeding to the example we recommend you review these articles which cover some foundations that will be made use of in the example:

Format Components

Here is what the source code repository for the ACM extension looks like:

.gitignore
.quartoignore
LICENSE
README.md
bibliography.bib
template.qmd
_extensions/
  acm/
    _extension.yml
    acm_proc_article-sp.cls
    sensys-abstract.cls
    include-in-header.tex
    acm-sig-proceedings.csl
    partials/
      doc-class.tex
      title.tex
      before-bib.tex

For the time being we’ll ignore all of the files above the _extensions directory (those files aren’t strictly part of the extension but rather provide documentation and a starter template—we’ll describe their usage below).

The _extensions directory contains one or more extensions—in this case it contains the acm format extension.
The _extension.yml file declares the format extension and provides default metadata and options for articles created for the format (we’ll do a deep dive into its contents below).
The acm_proc_article-sp.cls and sensys-abstract.cls files are LaTeX class files used by the ACM.
The include-in-header.tex file provides some standard content included in the preamble of ACM articles.
The acm-sig-proceedings.csl is a Citation Style Language (CSL) file that enables rendering of citations and bibliographies according to the standards of the ACM.
The partials directory contains some .tex files that override various parts of the standard Pandoc LaTeX template (see Article Templates to learn more about partials).

Here’s what the contents of _extension.yml look like:

title: ACM Journal Format
author: Charles Teague
version: 0.1.0
quarto-required: ">=1.2.0"
contributes:
  format:
    common:
      csl: acm-sig-proceedings.csl
      number-sections: true
    pdf:
      shift-heading-level-by: -1
      template-partials:
        - partials/before-bib.tex
        - partials/doc-class.tex
        - partials/title.tex
      include-in-header:
        - include-in-header.tex

As you can see, many of the files located in the _extensions/acm folder are referenced here. Also note that while there are several options declared for the pdf format, there are also some options declared in common—these options will be applied to pdf and will also be applied to other format variants (e.g. HTML) when they are developed.

Format Template

Now let’s return to the files outside of the _extensions directory. The LICENSE and README.md files provide documentation that is good form to include in all extensions. The .gitignore files masks selected files out of version control. The remainder of the files provide a format template that make it easier for users to get started with your format.

For any custom format that includes a template.qmd, users can get started with the format with a command like this:

Terminal

quarto use template quarto-journals/acm

The files included within the ACM template are:

template.qmd is a starter template for using the format. Here’s what the YAML document options for the template look like:

---
title: Short Paper
author:
  - name: Alice Anonymous
    email: alice@example.com
    affiliation: Some Institute of Technology
  - name: Bob Security
    email: bob@example.com
    affiliation: Another University
abstract: |
  This is the abstract.
  It consists of two paragraphs.
format:
  acm-pdf: 
    keep-tex: true  
bibliography: bibliography.bib
---

bibliography.bib is a sample bibliography referenced by template.qmd

Note that the schema for author information used here is relatively straightforward. See the article on Authors & Affiliations to learn about more sophisticated schemas for author information.

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 acm example, users could install your extension and associated template as follows (where quarto-journals is the GitHub organization hosting the repo):

Terminal

quarto use template quarto-journals/acm

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 are working with an existing project:

Terminal

quarto add quarto-journals/acm

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.

Multiple Formats

A single format extension can support more than one output format. For example, an extension may target html and pdf output. To support multiple formats in your extension, you can add additional base formats to the contributes / format key like so:

contributes:
  format:
    html:
      # html-specific options
    pdf:
      # pdf-specific options

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-specifc
    pdf:
      # pdf-specifc

Format Resources

You can usually include other files and resources within a format extension by placing those files within the extension directory and using relative paths to reference them in your _extension.yml metadata file. These relative paths will be properly handled as your extension’s metadata is merged with the rendered document metadata.

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:
    pdf:
      format-resources:
        - plos2015.bst

Extension Embedding

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

Terminal

quarto create extension format:pdf myformat
cd myformat
quarto add quarto-ext/fancy-text --embed myformat

For example, here we want to make the fancy-text extension (which provides special formatting for the words \(\LaTeX\) and BibT_EX) available for users of the jss custom format:

Terminal

quarto add quarto-ext/fancy-text --embed jss

This will produce the following output:

Output

quarto-journals/jss
└── _extensions
    └── jss
        ├── _extensions
        │   └── quarto-ext
        │       └── fancy-text
        └── partials

This will add the quarto-ext/fancy-text extension into the 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 users might already have installed.

Learning More

Here are some additional learning resources you may find valuable:

The source code for the Journal article formats available from the quarto-journals GitHub organization.
The GitHub template repository for creating new Journal formats. The code in the template repository is heavily annotated so creating a new repository using this template and experimenting with it is an excellent way to learn.
In depth treatment of creating Article Templates for Journals (including how to use partials to compose templates)
Review of the schema and options for expressing and rendering Authors & Affiliations.

Footnotes

This is most common in the the case of PDF based formats which have a secondary step of converting the LaTeX produced by Pandoc into a PDF. If there are files that are referenced indirectly by the LaTeX, they will need to be discoverable and should typically be copied into the same directory that contains the LaTeX input.↩︎