Quarto

Author
Affiliation

Miquel Perello Nieto

University of Bristol

Gentle reminder of the publishing workflow

The publishing workflow is the process in which external resources are prepared and collated together with the help of an authoring tool and subsequently rendered with a formatting tool to generate a publishable output that can be delivered in various forms. This is visualised by the following figure.

---
Publishing workflow
---
%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%
flowchart LR
  
    E1("(1)\nExternal resources"):::external -.-> A1
    A1{{"(2)\nAuthoring tool"}} --> I1("(3)\nText + Figures +\nCode + Tables + ..."):::input
    I1 --> P1{{"(4)\nFormatting tool"}}
    P1 --> O1["(5)\nFormatted\nOutput"]:::output
    O1 -.-> D1{{"(6)\nDelivery system"}}:::delivery
    classDef external fill:#eee,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5;
    classDef input fill:#ffa;
    classDef output fill:#faa;
    classDef delivery stroke:#666,stroke-width:2px,stroke-dasharray: 5 5;

An example of a publishing workflow is the following. A research group may carry out an investigation which ends up with (1) data, figures, analyses, and results, those resources are put together with an (2) authoring tool like Overleaf which produces an (3) organised hierarchy of files and text that includes formatting information, then using a (4) formatting tool like pdfLaTeX all the artefacts are combined into a (5) pdf document that can be (6a) printed as a stand-alone document, or (6b) included into the proceedings of a conference.

Publishing paradigms

The creation of research or academic material usually involves the production of slides, documents, posters and other output formats from the same material. There are different paradigms to create publishing material:

Quarto is a formatting tool

Formatting tools take input artefacts produced by authoring tools and produce publishable formatted output. While many of the authoring tools discussed in the previous section are well-known, there have been many recent developments in formatting tools that deserve to be better known in the academic community as they take opportunities for publishing training material to the next level. In the previous section we described the two paradigms (SISO) and (SIMO). In this section we describe some formatting tools that can be used for the SIMO paradigm.

%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%

flowchart LR
  
    E1("External resources"):::external -.-> A1
    A1{{"Authoring tool"}} --> I1("Text + Figures +\nCode + Tables + ..."):::input
    subgraph "Quarto, pdflatex, xelatex, pandoc, ..." 
      direction LR
      I1 --> P1{{"Formatting tool"}}
      P1 --> O1["Formatted\nOutput"]:::output
    end
    classDef external fill:#eee;
    classDef input fill:#ffa;
    classDef output fill:#faa;

Quarto as a Single-In-Multi-Out

More recent publishing systems allow the generation of multiple types of publication formats from a joint set of input artefacts. We refer to this paradigm as Single-In-Multi-Out (SIMO). This paradigm offers various benefits, among them: - keeping the artefacts in a single, well-defined location which facilitates consistency, management and findability; - keeping a unique source of history changes and versions which is useful for auditing and transparency; and - not duplicating artefacts that are not changed between different publishing systems.

%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%

flowchart LR
    I1("(3)\nText + Figures + \n Code + ..."):::input --- dummy2{{"(4) Quarto\nFormatting tool"}}
    dummy2 --> O1["(5a) Published \n Paper \n (PDF)"]
    dummy2 --> O2["(5b) Presentation \n Slides \n (PPTX/PDF)"]
    dummy2 --> O3["(5c) Poster \n (PPTX/PDF)"]
    dummy2 --> O4["(5d) Computational \n Notebook \n (Colab)"]
    classDef input fill:#ffa;
    style O1 fill:#fca
    style O2 fill:#bff
    style O3 fill:#f99
    style O4 fill:#bfb

Nowadays, the SIMO type of formatting tool is becoming more common, and we focus on the state-of-the-art formatting tools that fall into this category in this roadmap. The roadmap document itself is an example of one particular tool (Jupyter Book), while the rest of the document and use cases also include examples built with Quarto. A description of these and other publishing tools is provided with more detail in the next section .

Installation and usage

  • Get started documentation: quarto.org/docs/get-started/
  • Open-source repository in GitHub: Quarto-cli
  • Create a project with quarto create project
    • Type: default, website, blog, manuscript, book, confluence
  • Build project with quarto render
  • Preview with quarto preview (it autobuilds and updates when changes in the source files are detected).

Authoring for Quarto

Authoring tools facilitate the creation of input artefacts (e.g. plain text, markup language, tables, figures, code, or equations) which will be compiled and rendered by a formatting tool to generate publishable outputs. For example, a markup language editor to create LaTeX is an authoring tool, while pdflatex, XeLaTeX, or LuaTeX are formatting tools that compile input artefacts to pdf. These tools need to integrate metadata about the format in which the artefacts need to be formatted in different output types. For example, the font of the text and its position, the position of figures, tables and other elements. In this roadmap we focus on authoring tools that can be used for the purpose of multi-output publishing systems. We provide some guidelines on the type of files that need to be considered during the authoring process, which tools can directly help on the generation of those artefacts. We consider the collaboration of teams in the authoring process as a desirable feature.

%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%
flowchart LR
  
    E1("External resources"):::external -.-> A1
    subgraph "Vim, NeoVim, Notepad" 
      direction LR
      A1{{"Authoring tool"}} --> I1("Text + Code +\nTables + ..."):::input
    end
    I1 --> P1{{"Formatting tool"}}
    P1 --> O1["Formatted\nOutput"]:::output
    classDef external fill:#eee;
    classDef input fill:#ffa;
    classDef output fill:#faa;

Authoring tools that do not incorporate part of the formatting are rare, as it is common to provide at least a preview of the formatted output. Examples of authoring that can be separated from the formatting step are simple text editors like vim, NeoVim, Notepad, and general-purpose Integrated Development Environments (IDEs).

Authoring with formatting

There are authoring tools that incorporate a formatting tool. While in some situations it is a good practice to separate the two aspects, some computer programs integrate them in one tool that may (or may not) provide access to the intermediate artefacts. For example, Overleaf provides an online collaborative authoring platform that integrates with pdfLatex in the back-end.

%%{ init : { "theme" : "neutral", "flowchart" : { "curve" : "stepBefore" }}}%%
flowchart LR
  
    E1("External resources"):::external -.-> A1
    subgraph "IDE + Quarto, HackMD, Notion, Typst, Overleaf..." 
      direction LR
      A1{{"Authoring tool"}} --> I1("Text + Figures +\nCode + Tables + ..."):::input
      I1 --> P1{{"Formatting tool"}}
      P1 --> O1["Formatted\nOutput"]:::output
    end
    classDef external fill:#eee;
    classDef input fill:#ffa;
    classDef output fill:#faa;

Integrated Development Environments

The separation of the source code and the publishable outputs is something that all Integrated Development Environments (IDEs) provide. These are tools for writing computer programs that commonly require a compilation phase which is usually integrated in the same tool. The idea of authoring tools that can create generic input artefacts that are later combined by a formatting tool is very similar to the common process followed in programming compiled programming languages. This has facilitate the adoption of IDEs as authoring tools. Microsoft Visual Studio and Posit Workbench (formerly RStudio) have tools to work with the Quarto environment. Both of them provide options for collaborative and contemporaneous editing.

Then, what is Quarto?

Quarto is an open-source publishing system with the objective of facilitating the creation of scientific content. Quarto is sponsored by Posit, and follows the development of the R Markdown publishing system extending the focus from the programming language R to Python, Julia and Observable. It supports Jupyter notebooks, markdown and their own extension Quarto markdown. The conversion to different output formats is done with pandoc, which is able to produce presentations (Reveal.js), dashboards, websites, blogs, books, PDFs, Microsoft Word, ePub and more. Quarto is integrated into multiple authoring environments like Microsoft Visual Studio, Jupyter Lab, Rstudio, and Atlassian Confluence among others.

Key points

  • Quarto:
  • Quarto supports dynamic content with Python, R, Julia and Observable
  • programming languages.
  • Quarto uses pandoc to convert the input artefacts to its output.
  • Quarto supports plain text markdown, Jupyter notebooks and an augmented
  • markdown,
  • Integration with Posit Connect (former RMarkdown), Atlassian Confluence, Visual Studio,
  • Built with quarto render
  • Has a preview mode quarto preview which autobuilds and updates when changes in the source files are detected.