3  Quarto workflow

In this section we are going to explain some more details about the creation process of documents in Quarto, to better understand the components involved in this process and the configuration options we have available. The Figure 3.1 summarizes at a high level the phases of creating a document with Quarto.

Figure 3.1: Content creation process with Quarto. Source: RStudio.

3.1 Document assembly line

We can consider the process of creating a document in Quarto as a chain assembly in which various software tools are applied sequentially to produce the final document in different output formats.

  • Quarto: The first agent that intervenes in the interpretation of the file with extension .qmd is Quarto. The program must be previously installed on our computer to that the development environment that we decide to use (RStudio, Microsoft VS Code, etc.) can find it. Quarto is responsible for interpreting the content of the file and considering the different configuration options that we have inserted in the header of the document, as well as in executable code fragments, to delegate the construction tasks of the different parts of the document to other tools.

    Quarto is also responsible for automatically inserting some authoring elements of documents (such as callouts, explained in Section 4.5.4), while the generation of other elements (numbering of figures, tables, bibliographic citations, etc.) It is delegated to other tools like Pandoc.

  • Code execution engine (engine): One of the great advantages of document production in Quarto is the possibility of inserting fragments of executable code in our documents. Quarto can work with different engines (engines in Quarto terminology) that interpret the code and return the result of its execution to integrate it into the final document.

    • All R language code blocks use the knitr package as engine execution.

    • Executable code blocks in other languages ​​supported in Quarto (Python, Julia, Observable) use the kernel available in the Jupyter tool for execution, except in the explicit case that blocks of code are combined in R and Python in the same document.

    • In the particular case that the same document combines code blocks in R and Python, then the Knitr tool is used for the R code along with the R reticulate package to execute the blocks written in Python. This combination has the additional advantage that it is possible “pass” variables and results between the R and Python runtimes, so that we can use variables and data structures created in the R part within our Python code and vice versa.

  • Markdown: The intermediate product of all the previous phases is a file in Markdown (.md extension), which already integrates the formatted textual content and many of the results and elements additional generated by the different tools that have come into play up to this point. If useful, this intermediate file can be stored for review or for use it for other purposes. This file is then sent to Pandoc for the last stage document creation.

  • Pandoc: The Pandoc project offers a software tool to translate documents between different information representation formats. As you can quickly see On the main page of the project, the list of supported formats is really extensive. For purposes Practically speaking, Quarto uses Pandoc’s ability to receive as input a document in Markdown and generate output in three possible formats: HTML, DOC/DOCX or PDF. The Markdown file must include specific syntax to encode certain elements (cross-references, bibliographic citations, figures, tables, equations, etc.) that we will present in the following chapters, so that Pandoc can interpret these elements and represent them appropriately in each output format.

Finally, it should be noted that document viewing programs are needed to load the documents. Output documents, depending on format: web browser (HTML), MS Word (DOC/DOCX files), PDF viewer (PDF files).

3.2 Producing HTML

The default option for the output format of Quarto documents is to generate an HTML document, which can be viewed with most modern web browsers. This output format has several advantages:

  • It is quite likely that the recipient of the document already has one or more browsers installed on your system to view the document, if we send or share it directly to you.

  • It is easier to publish this type of documents on the Web, using one of the different platforms available for this purpose:

    • Quarto Pub, a document publishing service that allows are publicly accessible.

    • Individual documents (see Chapter 4) and books or collections of Documents (see Chapter 5) can be published easily and quickly on publishing sites. hosting software projects such as GitHub or GitLab, which also provide hosting services version control, bug/improvement reporting management, documentation, testing, etc.

3.3 Producing PDF

Unlike in HTML, when we generate PDF documents an additional compilation step is added of the document at the end of the entire assembly line, using LaTeX and the compilation engine XeLaTeX to generate PDF output. Therefore, if we select this output option it is essential have a TeX/LaTeX distribution previously installed on our system, to compile and generate the documents. If we do not have any yet, you can install TinyTeX, a lightweight distribution of TeX Live which is much smaller in size (~100 MB vs. to more than 4 GB of full TeX Live).

3.3.1 Customising PDF documents

Predefined LaTeX document templates can be used. By default, Quarto uses various templates from the LaTeX package collection koma-script.

Some of these templates can work relatively easily in Quarto, while Others require some adaptation, for which some knowledge about Latex. This is probably a more advanced topic for many users, so for now I don’t We are going to discuss it in this introductory workshop.

However, as an example, we offer below a list of some examples that illustrate the enormous possibilities of this type of templates:

  • Professor R.J. Hyndman has published Monash University Quarto document templates, that can be used as a starting point to customize them in our own projects.

  • The repository Awesome Quarto Thesis collects a list of Quarto templates to generate TFG/TFM reports and doctoral theses for some universities. Also linked is a generic extension template for Quarto, designed to make it easier for other users to customize it according to the criteria marked by their own institution to generate these jobs.