Article Templates

Overview

Journal article formats often require fine grained control of generated output as well as the ability to use Journal-specific commands and directives. This can be achieved for Quarto formats by providing custom Pandoc templates (LaTeX and/or HTML). Often these templates are a mix of Journal-specific LaTeX and standard directives required by Pandoc. This article describes how to create custom Journal templates that behave well with Pandoc and produce high-fidelity publisher ready output.

Templates

Quarto uses Pandoc templates to generate the rendered output from a markdown file. A Pandoc template is a mix of format specific content and variables. The variables will be replaced with their values from a rendered document. For example, the most basic template looks like:

mytemplate.tex

\documentclass{scrartcl}
\begin{document}
$body$
\end{document}

In the above template, the $body$ variable will be replaced with the LaTeX that is generated from the body of the document. If the body text is Hello **world**! in Markdown, the value of $body$ will be Hello \textbf{world}!.

By providing your own custom template used when rendering, you have complete control of the final output. You can provide this custom template to be used when rendering like this:

format:
  pdf:
    template: mytemplate.tex

For more complete information about template syntax, see Template syntax.

Template Partials

Replacing an entire template gives you complete control of the rendered output, but many features of Pandoc and Quarto depend upon code and variables that appear in the built in templates. If you replace the entire template and omit these variables, features will not work properly.

It’s therefore recommended that you take one of two approaches when authoring templates:

Selectively replace partials that exist within the master LaTeX or HTML template.
Replace the entire LaTeX or HTML template, but then include partials provided with Quarto to ensure that your template takes advantage of all Pandoc and Quarto features.

Below we’ll cover both of these approaches. Note that after reviewing this documentation you may also want to check out the source code of formats published on quarto-journals for additional examples.

Replacing Partials

For LaTeX / PDF and HTML output, Quarto provides built in templates that are composed of a set of ‘partial’ template files. For these formats, you may replace portions of Quarto’s built in template, allowing you to customize just a portion of the template without needing to replace the whole thing. A simple partial to provide custom handling of the document title in LaTeX looks like:

title.tex

\title{$title$}
\author{$for(author)$$author$$sep$ \and $endfor$}
\date{$date$}

You provide this partial to Quarto like:

format:
  pdf:
    template-partials:
      - title.tex

When Quarto renders a document with a partial, it will use the built in template but replace a portion of the template with the provided partial. In the above case, the LaTeX title will be replaced with the implementation provided as the partial, while the rest of the built in template will be used.

Note that the name of the partial files is important. You choose which portion of the template to replace by providing a partial with that name. You can see the list of partials available in HTML Partials and LaTeX Partials below.

Including Partials

In addition to replacing built in partials with your own, you may also choose to use built in partials when composing your own template. This allows you to create a template that takes advantage of the capabilities and options provided by Quarto and Pandoc without copying and maintaining the entire template code. For example, you can use the $pandoc.tex()$ partial to include pandoc configuration for text highlighting, tables, graphics, tight lists, citations, and header includes:

my-template.tex

\documentclass{scrartcl}
$pandoc.tex()$
\begin{document}
$body$
\end{document}

This modular approach means that is easier to implement templates that:

Include required elements of Pandoc templates
Support general Pandoc features and options
Provide only the minimal LaTeX or HTML rather than being required to provide all of it

LaTeX Partials

View the Quarto LaTeX template and partials source code here. Note that latex.template is a copy of the complete Pandoc template that the Quarto template and partials is based upon.

template.tex: The core LaTeX template which includes the basic document skeleton plus the following partials. This can’t be replaced as a partial, instead use the template option to provide your own template.
doc-class.tex: Contains the document class declaration and options. By default we provide the identical document class that Pandoc provides, implementing many features. If you override this (which will be common), you will need to either implement support for the document class options or be aware that those options (e.g. font-size, paper-size, classoption, etc…) will not be supported in your output.
before-title.tex: Appears in the document premable just before the title block. By default, this partial is empty.
title.tex: Provides configuration of document metadata for writing the title block. Note that in addition to these templates and partials, Quarto will also make normalized authors and affiliations data available to the template, making is easy to write custom title blocks against a standard schema.
before-body.tex: Implements the frontmatter, title page, and abstract.
after-body.tex: Provides a placeholder to attach content at the end of the body.
toc.tex: Creates the table of contents, list of figures, and list of tables.
before-bib.tex: Placed after the content of the document, but before the bibliography. By default contains nothing.
biblio.tex: Creates the bibliography.
pandoc.tex: This includes configuration for text highlighting, tables, graphics, tight lists, citations, and header includes. In general, this partial must always be included within your custom template. In some circumstances, you may know that certain capabilities will not be needed, so you this partial is further composed of the following partials, which could be used if sensible:

tightlist.tex: Provides the tight list command.
tables.tex: Provides configuration for the output of tables, table captioning, and footnotes within tables.
graphics.tex: Provides image scaling and placement configuration.
citations.tex: When using CSL references, provides configuration and commands for outputting the bibliography.

See the full source code for the Quarto LaTeX template to see how these partials are invoked by default.

HTML Partials

View the Quarto html template and partials source code here. Note that html.template is a copy of the complete Pandoc template that the Quarto template and partials is based upon.

Quarto’s HTML template is broken down into the following components:

template.html: The core HTML template which includes the basic document skeleton plus the following partials. This can’t be replaced as a partial, instead use the template option to provide your own template.
metadata.html: Populates basic document metadata into the HTML document head. More advanced metadata elements are not currently implemented within this template (e.g. social media, academic metadata) but are implemented as post processors.
title-block.html: Provides the title block for the document.
toc.html: Provide the table of contents target for the document

Revealjs Partials

View the Quarto Revealjs template and partials source code here. Note that revealjs.template is a copy of the complete Pandoc template that the Quarto template and partials is based upon.

template.html: The core Revealjs templates which includes the basic presentation skeleton plus the following partials. This can’t be replaced as a partial, instead use the template option to provide your own template.
title-slide.html: HTML used for the presentation title slide.
toc-slide.html: HTML used for the presentation table of contents.