0042-callouts.Rmd

# Callouts {#callouts}

## Callout generator

Want to skip all the technical stuff? Use the widget below to create your callouts instantly.

:::: {.callout type="red" title="Callout generator" icon="fas fa-gear" style="plain" collapsible="true"}

```{r, echo=FALSE, results='asis'}
htmltools::tags$iframe(
  src = "callout_generator.html",
  style = "width: 100%; height: 75vh; min-width: 650px; border: none;"
)
```
::::


    
## About callouts

:::: {.callout type="blue" title="What's a callout?"}

This is a callout! So is the Callout Generator above - that one has a different *type*, *style*, and is *collapsible*. You can customize callouts in many different ways. 

The content area inside a callout is standard Markdown. You can include:

-   Paragraphs and line breaks
-   Bulleted (`-`) or numbered (`1.`) lists
-   **Bold** and *italic* text
-   `inline code`
-   Fenced code blocks
-   Links and images
-   Even other nested callouts!

::::

Callouts are created using a custom code block using the following syntax. Options are listed in the sections below. Note that there must be a blank line after the opening `:::: {....}` line and before the final closing `::::` line.

```markdown
:::: {.callout <options>}

This is the content of the callout. You can write any Markdown here.

::::
```

## Callout options

Customize each callout by adding attributes inside the curly braces `{}`.

``` {r, echo=FALSE, message=FALSE}
# Load necessary libraries
library(knitr)
library(kableExtra)
library(dplyr) # Using dplyr for the pipe operator %>%

# 1. Create the Data Frame with the new data
table_data <- data.frame(
  Attribute = c("`type`", "`style`", "`title`", "`icon`", "`collapsible`", "`center_title`"),
  Required = c("**Yes**", "No", "No", "No", "No", "No"), # Keep bold markdown for "Yes"
  Description = c(
    "Sets the color scheme.", 
    "Defines the visual style.", 
    "Text for the callout's title. Can include Markdown.", 
    "Controls the icon next to the title.", 
    "Makes the callout a dropdown.", 
    "Centers the title (static callouts only)."
  ),
  ExampleValues = c(
    "`\"red\"`, `\"blue\"`, `\"green\"`, `\"yellow\"`, `\"purple\"`, `\"orange\"`, `\"gray\"`",
    "`\"regular\"` (default), `\"important\"`, `\"subtle\"`, `\"plain\"`",
    "`\"Important Note!\"`, `\"**Action Required**\"`",
    "`\"true\"` (default), `\"false\"`, or [any free FontAwesome icon class](https://fontawesome.com/icons/) (e.g., `\"fas fa-lightbulb\"`)",
    "`\"true\"` (default), `\"false\"`",
    "`\"true\"`, `\"false\"` (default)"
  )
)

# 2 & 3. Generate kable and apply column widths
table_data %>%
  kable(
    format = "html",
    col.names = c("Attribute", "Required?", "Description", "Example Values"), # New Column Headers
    escape = FALSE # Allows Markdown within cells (like **Yes** and code backticks)
  ) %>%
  kable_styling(
    bootstrap_options = c("striped", "hover", "condensed"),
    full_width = TRUE 
  ) %>%
  # Apply specific widths to the four columns
  column_spec(1, width = "10%") %>% # Attribute
  column_spec(2, width = "5%", extra_css = "text-align: center;") %>% # Required? (Centered)
  column_spec(3, width = "35%") %>% # Description
  column_spec(4, width = "50%") # Example Values (The widest column)
```


## Default icons

If you set `icon="true"` or omit the `icon` attribute, a default icon will be shown based on the `type` you've chosen. Here are the defaults:

``` {r, echo=FALSE, message=FALSE}

# 1. Create the Data Frame
# The column names here are for R's internal use. We set the display names later.
table_data <- data.frame(
  Color = c("`red`", "`blue`", "`green`", "`yellow`", "`purple`", "`orange`", "`gray`"),
  DefaultIcon = c(
    '<i class="fas fa-triangle-exclamation" style="color: #C0392B;"></i>',
    '<i class="fas fa-circle-info" style="color: #2980B9;"></i>',
    '<i class="fas fa-circle-check" style="color: #229954;"></i>',
    '<i class="fas fa-bell" style="color: #FFC107;"></i>',
    '<i class="fas fa-star" style="color: #8E24AA;"></i>',
    '<i class="fas fa-fire" style="color: #FB8C00;"></i>',
    '<i class="fas fa-comment-dots" style="color: #757575;"></i>'
  ),
  IconClass = c("`triangle-exclamation`", "`circle-info`", "`circle-check`", "`bell`", "`star`", "`fire`", "`comment-dots`")
)

# 2 & 3. Generate kable and apply column widths
table_data %>%
  kable(
    format = "html", # Ensure it generates an HTML table
    col.names = c("`type` (Color)", "Default Icon", "Icon Class (`fas fa-...`)"), # Set the displayed column headers
    escape = FALSE # CRITICAL: Allows the HTML icon tags to render instead of showing the raw code
  ) %>%
  kable_styling(
    bootstrap_options = c("striped", "hover", "condensed"),
    full_width = TRUE # Table spans the full content width
  ) %>%
  # Apply specific widths to the columns
  column_spec(1, width = "20%") %>% # Color (20%)
  column_spec(2, width = "20%", extra_css = "text-align: center;") %>% # Icon (20%, centered)
  column_spec(3, width = "60%") # Icon Class (60%)

```

You can override any of these defaults by specifying a different icon class, for example: `icon="fas fa-lightbulb"`. Find more icons on the [Font Awesome website](https://fontawesome.com/icons?d=gallery&m=free&s=solid).

## Style examples

Note that the colors chosen below are arbitrary: colors and styles can be mixed and matched.

### Regular
:::: {.callout type="blue" title="Regular, Blue" style="regular"}

This is a blue callout with Regular styling.

::::

:::: {.callout type="blue" title="Regular, Blue, Collapsible" style="regular" collapsible=true}

This is a blue collapsible callout with Regular styling.

::::


### Important
:::: {.callout type="purple" title="Important, Purple" style="Important"}

This is a purple callout with Important styling.

::::

:::: {.callout type="purple" title="Important, Purple, Collapsible" style="Important" collapsible=true}

This is a purple collapsible callout with Important styling.

::::

### Subtle
:::: {.callout type="red" title="Subtle, Red" style="subtle"}

This is a red callout with Subtle styling.

::::

:::: {.callout type="red" title="Subtle, Red, Collapsible" style="subtle" collapsible=true}

This is a red collapsible callout with Subtle styling.

::::


### Plain
:::: {.callout type="orange" title="Plain, Orange" style="plain"}

This is an orange callout with Plain styling.

::::

:::: {.callout type="orange" title="Plain, Orange, Collapsible" style="plain" collapsible=true}

This is an orange collapsible callout with Plain styling.

::::

## Indenting callouts/nesting in lists

You can nest callouts inside other elements, such as lists, by indenting the entire callout block. The option In-List Nesting Level in the Callout Generator above will do this for you.

**To place a callout inside a list item or indent the callout, indent the entire `::::` block (including its opening and closing fences and all of its content) by four spaces.**

`````markdown
1.  This is the first item in the list.

2.  This is the second item, which will contain a callout.

    :::: {.callout type="green" style="subtle" title="This is an indented callout"}

    This entire callout block is indented, making it part of the second list item.

    - You can have other Markdown elements inside, like this list.
    - They must also be indented to be part of the callout.

    ::::

3.  This is the third item in the list, appearing after the callout.
`````

1.  This is the first item in the list.

2.  This is the second item, which will contain a callout.

    :::: {.callout type="green" style="subtle" title="This is an indented callout"}

    This entire callout block is indented, making it part of the second list item.

    - You can have other Markdown elements inside, like this list.
    - They must also be indented to be part of the callout.

    ::::

3.  This is the third item in the list, appearing after the callout.


## Advanced example
This example uses multiple attributes and contains rich Markdown content, including a fenced code block. **To prevent rendering issues when nesting code blocks, use a longer fence (e.g., five colons `:::::`) for the outer callout block.**

``````markdown
:::: {.callout type="gray" style="important" title="*Action Needed:* Review Workflow" icon="fas fa-clipboard-check" collapsible="true"}

### Step 1: Data Ingestion

Please ensure your data from `source_data/experiment_A.csv` has been correctly loaded.

- Check for missing values.
- Verify data types.

### Step 2: Pre-processing

The pre-processing script `scripts/01_preprocess.R` must be run before analysis.

```{r, echo=TRUE, eval=FALSE}
# Example snippet from the script
# source("scripts/01_preprocess.R")
# processed_data <- preprocess_data(raw_data)
```

### Step 3: Analysis & Reporting

Confirm that the final report `output/final_report.html` has been generated.

If you encounter any issues, please refer to the *Troubleshooting Guide* section.

::::

``````

::::: {.callout type="gray" style="important" title="*Action Needed:* Review Workflow" icon="fas fa-clipboard-check" collapsible="true"}
### Step 1: Data Ingestion

Please ensure your data from `source_data/experiment_A.csv` has been correctly loaded.

- Check for missing values.
- Verify data types.

### Step 2: Pre-processing

The pre-processing script `scripts/01_preprocess.R` must be run before analysis.

```{r, echo=TRUE, eval=FALSE}
# Example snippet from the script
# source("scripts/01_preprocess.R")
# processed_data <- preprocess_data(raw_data)
```

### Step 3: Analysis & Reporting

Confirm that the final report `output/final_report.html` has been generated.

If you encounter any issues, please refer to the *Troubleshooting Guide* section.

:::::