4.4 Quarto

Host Quarto on GitHub Pages.

To get started, change your project configuration _quarto.yml to use docs as the output-dir.

project:
  type: book
  output-dir: docs

Then, add a .nojekyll file to the root of your repository that tells GitHub Pages not to do additional processing of your published site using Jekyll (the GitHub default site generation tool):

touch .nojekyll
  • Note that .nojekyll’s location is different than that of bookdown, which is at /docs folder.

Benefits of Quarto:

4.4.1 Book Structure

book:
  chapters:
    - index.qmd
    - preface.qmd
    - part: dice.qmd
      chapters: 
        - basics.qmd
        - packages.qmd
    - part: cards.qmd
      chapters:
        - objects.qmd
        - notation.qmd
        - modifying.qmd
        - environments.qmd
    - references.qmd
  appendices:
    - tools.qmd
    - resources.qmd

  • The index.qmd file is required (because Quarto books also produce a website in HTML format). This page should include the preface, acknowledgements, etc.

  • The remainder of chapters includes one or more book chapters.

    You can divide your book into parts using part within the book chapters.

    Note that the markdown files dice.qmd and cards.qmd contain the part title (as a level one heading) as well as some introductory content for the part.

    If you just need a part title then you can alternatively use this syntax:

    book:
  chapters:
    - index.qmd
    - preface.qmd
    - part: "Dice"
      chapters: 
        - basics.qmd
        - packages.qmd

  • The references.qmd file will include the generated bibliography (see References below for details).

Syntax differences with R markdown:

  • Code chunks

    R markdown

    ```{r my-label, fig.cap = caption}

# R code
```

    Vs.

    Quarto

    ```{r}
#| label: fig-my-label
#| fig-cap: caption 

# R code
```

    Note that Quarto accepts Rmd’s way of specifying chunk options. The difference is that Quarto’s label for figures must start with fig-, while Rmd accepts any labels.

    ```{r label = "fig-my-label", fig.cap = caption}

# R code
```

4.4.2 HTML Theming

One simple theme

title: "My Document"
format:
  html: 
    theme: cosmo
    fontsize: 1.1em
    linestretch: 1.7

Enable dark and light modes

format:
  html:
    include-in-header: themes/mathjax.html
    respect-user-color-scheme: true
    theme:
      dark: [cosmo, themes/cosmo-dark.scss]
      light: cosmo

respect-user-color-scheme: true honors the user’s operating system or browser preference for light or dark mode.

Otherwise, the order of light and dark elements in the theme or brand will determine the default appearance for your html output. For example, since the dark option appears first in the first example, a reader will see the light appearance by default, if respect-user-color-scheme is not enabled.

As of Quarto 1.7, respect-user-color-scheme requires JavaScript support: users with JavaScript disabled will see the author-preferred (first) brand or theme.

Theme options

You can do extensive customization of themes using Sass. Bootstrap defines over 1,400 Sass variables that control fonts, colors, padding, borders, and much more. You can see all of the variables here:

https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss

Note that when you make changes to your local .scss, the changes will be implemented in-time. That is, you don’t need to re-build your website to see the effects.

Ref: https://quarto.org/docs/output-formats/html-themes.html

4.4.3 Cross References

  1. Add labels:

    • Code cell: add option label: prefix-LABEL
    • Markdown: add attribute #prefix-LABEL

  2. Add references: @prefix-LABEL, e.g.

    You can see in @fig-scatterplot, that...
prefix Renders
fig- Figure 1
tbl- Table 1
eq- Equation 1
sec- Section 1

Equations

$$
y_i = \beta_{i}'x + u_i.
$$ {#eq-cross_sectional_hetero}
  • @eq-cross_sectional_hetero gives Equation (1)
  • [-@eq-cross_sectional_hetero] gives only the tag (1)

You can customize the appearance of inline references by either changing the syntax of the inline reference or by setting options.

Here are the various ways to compose a cross-reference and their resulting output:

Type Syntax Output
Default @fig-elephant Figure 1
Capitalized @Fig-elephant Figure 1
Custom Prefix [Fig @fig-elephant] Fig 1
No Prefix [-@fig-elephant] 1

Note that the capitalized syntax makes no difference for the default output, but would indeed capitalize the first letter if the default prefix had been changed via an option to use lower case (e.g. “fig.”).

Change the prefix in inline reference using *-prefix options. You can also specify whether references should be hyper-linked using the ref-hyperlink option.

---
title: "My Document"
crossref:
  fig-prefix: figure   # (default is "Figure")
  tbl-prefix: table    # (default is "Table")
  ref-hyperlink: false # (default is true)
---

4.4.4 Equations

Load MathJax Config

Load mathjax.html in YAML

---
title: "Model specifications"
author: "GDP and climate"
date: "2025-05-13"
from: markdown+tex_math_single_backslash
format: 
  html:
    toc: true
    self-contained: true
    html-math-method: mathjax
    include-in-header: mathjax.html
---

In mathjax.html

<script>
MathJax = { 
    tex: { 
        tags: 'ams',  // should be 'ams', 'none', or 'all' 
        macros: {  // define TeX macro
            RR: "{\\bf R}",
            bold: ["{\\bf #1}", 1]
        },
    },
};
</script>

tags: 'ams' allows equation numbering

Math delimiters

Issue: Cannot use \( and \[ for math delimiters.
Fix: Add from: markdown+tex_math_single_backslash to YAML frontmatter. Source

---
title: "Quarto Playground"
from: markdown+tex_math_single_backslash
format:
  html:
    html-math-method: mathjax
---

Inline math example: \( E = mc^2 \)

Block math example:

\[
a^2 + b^2 = c^2
\]

form: Format to read from. Extensions can be individually enabled or disabled by appending +EXTENSION or -EXTENSION to the format name (e.g. markdown+emoji).

Extension: tex_math_single_backslash

Causes anything between \( and \) to be interpreted as inline TeX math, and anything between \[ and \] to be interpreted as display TeX math. Note: a drawback of this extension is that it precludes escaping ( and [.

Refer to Docs of Quarto and Pandoc:

Q: How to get rid of the qmd dependence file?
A: Use

format: 
  html:
    self-contained: true

4.4.5 Theorems

::: {#thm-line}
The equation of any straight line, called a linear equation, can be written as:

$$
y = mx + b
$$
:::

See @thm-line.

In Quarto, #thm-line is a combined command us .theorem #thm-line in bookdown. In bookdown, the label can be anything, does not have to begin with #thm-. But in Quarto, #thm-line is restrictive, it indicates the thm environment and followed by the label of the theorem line.

Theorem 4.1 The equation of any straight line, called a linear equation, can be written as:

\[ y = mx + b \]

See Theorem 4.1.

To add a name to Theorem, use name="...".

::: {#thm-topo name="Topology Space"}
A topological space $(X, \Tcal)$ is a set $X$ and a collection $\Tcal \subset \Pcal(X)$ of subsets of $X,$ called open sets, such that ...
:::

See Theorem @thm-topo.

Theorem 4.2 (Topology Space) A topological space \((X, \Tcal)\) is a set \(X\) and a collection \(\Tcal \subset \Pcal(X)\) of subsets of \(X,\) called open sets, such that …

See Theorem 4.2.

Change the label prefix:

---
crossref:
  cnj-title: "Assumption"
  cnj-prefix: "Assumption"
---
  • cnj-title: The title prefix used for conjecture captions.
  • cnj-prefix: The prefix used for an inline reference to a conjecture.

References: