Skip to main content

Content guidelines

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 the tags argument of search_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:

LearningLearning Objectives

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

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 echo is not set to FALSE.
  • 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., ```r instead 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 a 1. footnote text here immediately after the code chunk (similar for # <2> etc.). This works in functional code or non-functional code!
ExampleExample

Example of a footnote in a non-executing code chunk that includes R syntax highlighting:

```r
x <- 3 * 4 # <1>
```
1. This is an example of a footnote!

will render like:

x <- 3 * 4
1
This is an example of a footnote!
ExampleExample

Example of a code chunk (non-executing) that shows the header/footer backticks and curly-braced r.

```{{r code-chunk-name-or-whatever}}
x <- 3 * 4 
```

will render (but NOT execute) like:

```{r code-chunk-name-or-whatever}
x <- 3 * 4 
```

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:

Important

Use {.callout-important} to highlight things that the reader must pay attention to, or essential ideas and concepts.

Warning

Use {.callout-warning} to highlight common “gotchas” such as common user errors or unexpected behavior.

Caution

Use {.callout-caution} to indicate materials under development; consider using {.callout-warning} for other cases.

Note

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.

Tip

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.

ExerciseExercise

Use {.callout-exercise} for exercises. The current default numbers exercises within a given page. Click on the hint and answer callouts below to reveal the information in them.

Use {.callout-hint} for hints to the exercise - defaults to collapse=true for obvious reasons. Note they can be nested within an exercise, or stand-alone.

Use {.callout-answer} for answers to the exercise - defaults to collapse=true for obvious reasons. Note they can be nested within an exercise, or stand-alone.

ExampleExample

Use {.callout-example} for examples, e.g., example data or example.