Moving to Quarto

Figure 1: Featured image.

Essentially, I have the same reasoning as John Best:

I first published my personal website using the blogdown pacakge. There were some great walkthroughs to get everything set up and I even had Netlify automatically build and deploy every commit I pushed to Github. The Academic (now Wowchemy) theme was a de facto standard among academics (surprise), and seemed like an obvious choice. It looked nice and basically let you build your CV as the front page of your website. And it has clearly filled a niche, now offering different layouts for research groups and other uses.

As its use cases expanded, it got more complicated. Configuration moved from YAML to TOML at some point, configuration files and directories got moved around. I don’t need to update my webisite very often, but every time I did I had to chase down multiple minor versions’ worth of breaking changes, and remember to update Hugo.

- Positive Definite Ecology - Moving to Quarto (Best, 2022)

I also don’t update my website very often (something I’d like to remedy in the coming year), so I feel this pain deep in my soul. I’d considered changing over to the Hugo Apéro theme, which I find more visually pleasing than Wowchemy, but it doesn’t address the issue I run into involving focusing on the design and the details to the detriment of creating actual content. Quarto’s blog website is simple, efficient, and just as interactive, without all the bells and whistles that amount to nothing more than distractions.

It’s possible I’ll make the effort to port over the more useful posts from my old website. It’s equally possible that I won’t bother. We’ll see.

Some Quarto highlights

Some easy-to-find and use features of Quarto that I tend to use frequently. Should be clear that I use RStudio for this.

Margin content

A margin image

::: {.column-margin}
![A margin image](thumbnail.jpg)
:::

---

Two useful margin content options are asides and margin captions.

If you want some arbitrary text in the margin, it’s easy to do like this. This part lacks a footnote reference number.

[If you want some arbitrary text in the margin, it's easy to do like this. This part lacks a footnote reference number.]{.aside}

Putting a figure’s caption in the margin next to it is as easy as using these chunk options:

#| label: fig-margin-caption-example
#| fig-cap: "This is the caption for the figure."
#| cap-location: margin

You can set many of these on a per-instance, per-document, or even global level: Quarto - Article Layout

---

Citations

Using Quarto in RStudio makes it incredibly easy to use citations and cross-references.

Important

To natively insert a citation and add it to the document’s .bib file, you must be using the Visual editor.

If you want your citation style to be something other than the default, you’ll need to update the csl YAML key.

csl: apa.csl

You can save the file from here and place it in the document’s directory. Unfortunately, due to how the YAML works, you can’t put it in the global YAML.

Citing is the same in Quarto as it is in Rmd. Examples of different citation syntaxes can be found here.

Cross-Referencing

Cross-references are simple. You just need to remember to use the correct naming syntax. The Quarto documentation is good. Here are some brief examples:

The image at the top of the post has this syntax:

![Featured image.](thumbnail.jpg){#fig-featured}

This way, you can simply type See @fig-featured for an illustration. to get “See Figure 1 for an illustration.”

Same thing goes for plots and other chunk-based content. For example:

```{r}
#| label: fig-cars
#| fig-cap: "Cars"

plot(cars)
```

Figure 2: Cars

You can reference @fig-cars since we’ve given the chunk that label. Like so: see Figure 2.

Important

You can get the kind of chunk above using the #| echo: fenced chunk option.

Shortcodes

These are similar to Hugo’s shortcodes. A simple example is:

{{< meta title >}}

Which will display the title of whatever page it’s on, like so: Moving to Quarto. (You can escape them to get the literal shortcode text by adding one extra set of braces.)

References

Best, J. (2022). Moving to Quarto. https://www.posdefecology.net/posts/moving-to-quarto/moving-to-quarto.html