Quarto Document Best Practices

1 Why Quarto

I use quarto documents every day. It is used when I am developing, I use it for my website, and I use it for client presentations.

Quarto Benefits

• Version control is very nice for presentations
• Text, docs, code ouputs, plots, code, tests all in one place.
• Easy to make really good looking outputs
• Learn one tool for lots of formats - documents, presentations, websites, development
• Rendering to html is a option for sharing. It’s more powerful than pdf and everyone can open it in their browser.

I have some starter Quarto templates here that will be useful in conjunction with this post.

2 Text Formatting

Markdown

It’s important to get comfortable with markdown. I see people use markdown for text. But you need to mix in other features liberally such as:

• Bulleted or numbered lists
• Making accent words bold or italized
• Use single ticks to reference object and function names
• Use headings liberally
• Use hyperlinks to things you are referencing in quarto

Blockquotes are also useful

Panel Tabsets

Panel tabsets creates the tabs you click through in the Formatting Tips section. This is useful for limiting what’s shows on the screen and gives a really high quality feel above and beyond a pdf document. Use it to organize and make your document clearer and less static.

Callout Blocks

Callout blocks can be used extremely liberally in documents. In a given document or presentation I use them to organize content in color coded sections based on what I think makes most sense in the context.

Example Document Usage

• Recommended actions in a blue note callout blocks
• Definitions or clarification points in green tip callout blocks
• Discussion points or questions in gold warning callout blocks
• Problems or issues in red important callout blocsk

3 Code Formatting

The most important items for code cell formatting are controlling what’s included and what is hidden. Here are the top ones I use for that.

• Code
  • code-fold - Fold code with option to expand?
  • echo - Include code in your document?
  • include - Include code and outputs?
• Outputs
  • output - Include code outputs?
  • include - Include code and outputs?

Tip

To use a one of these directives start a code cell with #|.

For example #| echo: false will exclude that code cell from the document.

4 Document Setup

4.1 Front Matter

For documents here’s my default front matter. A few things that are important:

---
title: "My Title"
author: "Isaac Flath"
date: "9/20/2022"
format:
  html:
    css: 'styles.css'
    number-sections: true
    toc: true
    theme: cosmo
    highlight-style: tango
    code-fold: true
    self-contained: true
---

Tip

• number-sections makes the sections stand out more organization wise
• toc (table of contents) is clickable to jump to sections and I review it as my agenda at the start of meetings
• code-fold I often like to have all code folded by default and unhide what’s needed.
• self-contained is critical. This allows you to share the document for anyone to open in their browser with no hassle.

4.2 CSS

There were two things that bothered me about quarto:

• Table of contents was too light
• Major sections didn’t stand out enough

These are fixed with a short bit of css. I sometimes add an h2 gradient from lightblue to white as well.

.title.toc-ignore {
  font-weight: 1000;
}
h1:not(.title){
  background-image: linear-gradient(120deg, lightblue, blue);
}

Tip

In the frontmatter section it references a styles.css where this is stored.