Code Annotation

Overview

Code blocks and executable code cells in Quarto may now include line-based annotations. Annotations are added within an inline comment at the end of a line followed by a number within angle brackets (e.g. # <1>). Include an ordered list below the code block to provide the annotation contents. For example:

```r
num = 370 # <1> 
sum = 0

temp = num
while(temp > 0) {           # <2> 
  digit = temp %% 10        # <2>    
  sum = sum + (digit ^ 3)   # <2>
  temp = floor(temp / 10)   # <2>
}                           # <2>
```

1. This could be replaced by a call to gather the number from the user.
2. Compute the sum of the cube of each digit. If this sum equals the number, this is an Armstrong number.

This code will render as follows for HTML and PDF formats:

Annotation Syntax

Annotations for a code cell consist of two related elements:

  1. Each annotated line should be terminated with a comment (using the code cell’s language comment character) followed by a space and then an annotation number enclosed in angle brackets (e.g. # <2>). You may repeat an annotation number if the annotation spans multiple lines.

  2. An ordered list that appears immediately after the code cell which includes the contents of each annotation. Each numbered item in the ordered list will correspond with the line of code(s) with the same annotation number.

When annotations are output for non-HTML and non-PDF formats, the annotation numbers will instead be replaced with a label pointing to the line of code (or lines of code) to which the annotation text applies.

Annotation Style

For HTML output, there are three options for the display style of annotations:

below

By default (or if code-annotations: below is specified), code annotation text will appear below the code cell.

hover

Code annotation text will be displayed when the user hovers over the annotation marker for a line of code.

select

Code annotation text will be displayed when the user clicks on an annotation marker (selecting it). The annotation text can be dismissed by clicking the annotation marker once again.

Complete Example

Here’s an example that uses code-annotation: select rather than the default code-annotation: below:

Example Code

---
code-annotation: select
---

```{r}
num = 47 # <1>
factorial = 1
if(num < 0) { # <2>
  print("No factorial for negative numbers")
} else if(num == 0) {
  print("The factorial of 0 is 1")
} else {
  for(i in 1:num) {             # <3>
    factorial = factorial * i   # <3>
  }                             # <3>
  cat("Factorial :", format(factorial), "\n")
}
```

1. The number, this could instead be user input
2. Check is the number is negative, positive or zero
3. Actually compute the factorial

Example Output

num = 47
factorial = 1
if(num < 0) {
  print("No factorial for negative numbers")
} else if(num == 0) {
  print("The factorial of 0 is 1")
} else {
  for(i in 1:num) {
    factorial = factorial * i
  }
  cat("Factorial :", format(factorial), "\n")
}
1
The number, this could instead be user input
2
Check is the number is negative, positive or zero
3
Actually compute the factorial

Removing Annotations

For some formats, you may prefer to remove annotations. In this case, you can set code-annotations: none, which will remove the annotation comments for your code and suppress the output of the ordered list which contains the annotation text.

Disabling Annotation

You can disable code annotation by including the option code-annotations: false in your document. This will stop the processing of code annotations and leave your code (and the original ordered list) as is.