There are some tricks to getting Quarto to display certain information in a helpful way, especially around code. This document outlines some of those tricks to control how Quarto displays/executes code (or doesn’t, as the lesson requires).
See https://cambiotraining.github.io/quarto-course-template/materials/02-content_guidelines.html for ideas.
See also the style guide for suggestions on text case, learning objectives, code chunks, tabsets, images, links, and callout customization.
1 Headers and such
The lesson’s title in the YAML header is rendered as the page title (the top-level heading), and the site numbers sections automatically, so in the body of the lesson:
- Do not use a single-
#heading; start with##for the main sections of the lesson. (The existing lessons overwhelmingly follow this pattern.) - Use
###and####for subsections and sub-subsections. Try not to go deeper than four levels. - Don’t type numbers into headings; they are added automatically.
- Keep headings short and descriptive, since they populate the table of contents in the right sidebar.
- Don’t skip levels (e.g., a
####directly under a##).
1.1 YAML header
Each lesson needs a title, which is shown in the sidebar menu and at the top of the page. Lessons in the lessons package also commonly include:
categories: a list of topic tags, e.g.,categories: [r-basics, lecture, beginner]. These are what thetagsargument ofsearch_lessons()matches against, so reuse existing tags where possible.description: a one-sentence summary of the lesson.
---
title: Working in R & RStudio
categories: [r-basics, lecture, beginner]
description: "RStudio basics, running code in the Console and scripts, ..."
---
1.2 Learning objectives
Open each lesson with a block listing learning objectives, using a {.callout-learning} div (“By the end of this lesson, you will be able to: …”). The theme gives this callout a green style, a brain icon, and the title “Learning Objectives”.
Write it like this, placed right after the YAML header:
:::{.callout-learning}
By the end of this lesson, you will be able to:
- Navigate the basics of the RStudio interface
- Run code and basic arithmetic in the Console
- Use the Help pages to look up function documentation
:::
which will render like:
2 Code formatting
- code that needs to be run, identical to what we want to show the reader: just write it in a regular R code chunk, and make sure
echois not set toFALSE. - code that needs to be run, but is different than we want to show the reader, e.g., reading in a file from a different source than presented in the lesson:
#| include: false- this lets the chunk execute, but conceals the code. If you want the reader to see different code, use a non-executing code chunk - one of the options below. - code that doesn’t need to be run: enclose in code block fence with language name next to it for syntax highlighting (e.g.,
```rinstead of in curly braces```{r}used for a functioning code block!). - code that should not execute but you want to show the code chunk header and footer along with the code, begin with a double-curly-bracket r in the header:
```{{r}}. Use this when you want to show the reader how to write an actual code chunk, possibly including options in the header portion. - optional, use footnotes by including
# <1>at the end of a line, then a1. footnote text hereimmediately after the code chunk (similar for# <2>etc.). This works in functional code or non-functional code!
3 Callouts
Quarto offers some built-in callout blocks to set content off against the normal body text. Note that we’ve customized the colors of our callouts to better match our course styling (see the nceas-learning-hub/theme extension in _extensions).
3.1 Standard callouts
There are five built-in callouts signalling different levels of urgency:
- tip
{.callout-tip} - note
{.callout-note} - caution
{.callout-caution} - warning
{.callout-warning} - important
{.callout-important}
See the callout reference for how to create these.
Based on the color and icons, here are recommendations on when and how to use these, in descending order of urgency:
Use {.callout-important} to highlight things that the reader must pay attention to, or essential ideas and concepts.
Use {.callout-warning} to highlight common “gotchas” such as common user errors or unexpected behavior.
Use {.callout-caution} to indicate materials under development; consider using {.callout-warning} for other cases.
Use {.callout-note} to communicate deeper ideas or understandings that are not critical to understanding the lesson at hand. The instructor might skip over these while teaching. If the reader does not read this, they may miss out, but nothing bad will happen.
Use {.callout-tip} to communicate key points and helpful tips and tricks. (Learning objectives have their own callout; see above.)
3.2 Custom callouts
There are currently five custom callouts for different types of content:
- exercise
{.callout-exercise} - hint
{.callout-hint} - answer
{.callout-answer} - example
{.callout-example} - learning objectives
{.callout-learning}(see above)
These custom callouts work thanks to Tavares, H., van Rongen, M., Cardona, A. (2024). Course Development Guidelines. https://cambiotraining.github.io/quarto-course-template/. Unfortunately, the title is not responsive to the title argument in the callout or to the header-style titling that the built-in callouts can use. The collapse option also seems to be unresponsive currently.