flowchart LR qmd --> J([Jupyter]) qmd --> K([knitr]) J --> md K --> md md --> P([pandoc]) P --> pdf P --> html P --> docx
Authoring Essentials
Session 2
Session Overview
Session Objectives
This session focuses on building foundational skills in Quarto authoring, covering enhanced markdown capabilities, YAML configuration, and document structuring best practices.
Learning Objectives
By the end of this session, participants will be able to:
- Create well-structured documents using enhanced Quarto markdown features.
- Configure documents using YAML headers for different output formats.
- Use advanced formatting features including callouts, cross-references, and tabsets.
Markdown Basics
Text Formatting Essentials
Basic text formatting you’ll use every day:
- Bold text with
**bold**or__bold__. - Italic text with
*italic*or_italic_. - Bold and italic with
***text***. - Superscript2 with
superscript^2^. - Subscript2 with
subscript~2~. Verbatim codewith backticks.
Headers Structure Your Content
Headers create your document structure and enable automatic table of contents generation.
markdown
# Heading 1 - Document Title
## Heading 2 - Major Sections
### Heading 3 - Subsections
#### Heading 4 - Minor Sections
##### Heading 5 - Rare Usage
###### Heading 6 - Very Rare
Tip
Add a empty lines before and after!
Lists
Important
Quarto requires empty lines before and after lists to ensure proper rendering!
Unordered Lists:
markdown
- First item
- Second item
- Third itemOrdered Lists:
markdown
1. First step
2. Second step
3. Third stepLists - Nested
Important
The number of spaces for indentation does not matter, but the list marker must be aligned with the first character of the parent item. Items marked bad below show incorrect alignment of nested content.
markdown
- First item
```r
print("Hello, World!")
```
- Second item (**bad**)
::: {.callout-tip}
Here is a tip!
:::
- Sub item
- Third item
::: {.callout-tip}
Here is a tip!
:::
- Sub itemmarkdown
- First item
```r
print("Hello, World!")
```
- Second item (**bad**)
::: {.callout-tip}
Here is a tip!
:::
- Sub item
- Third item
::: {.callout-tip}
Here is a tip!
:::
- Sub itemWorking with Code
Inline code: Use single backticks
markdown
The `print()` function outputs text.
Tip
Code highlighting for inline code:
markdown
The `print()`{.python} function outputs text.Code blocks: Use triple backticks with optional language
markdown
```python
def hello_world():
print("Hello, Quarto!")
```
Note
The syntax highlighting is provided by skylighting
Tables Made Simple
markdown
| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
: Demonstration of pipe table syntax| Default | Left | Right | Center |
|---|---|---|---|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
Use colons (:) to control alignment:
:---for left alignment.---:for right alignment.:---:for centre alignment.
See Table basics for more.
Mathematical Expressions
Inline maths: $E = mc^2$ renders as \(E = mc^2\).
Display maths: Use double dollar signs (on separate lines).
markdown
$$
E = mc^2
$$Define custom LaTeX macros in hidden blocks for reuse across your document, see Markdown Basics - Equations
Footnotes and References
Standard footnotes:
markdown
Here is a footnote reference[^1].
[^1]: Here is the footnote content.Inline footnotes:
markdown
Here is an inline note^[Much easier to write!].
Important
Footnote identifiers must be unique within the document.
Figure Basics
Basic
markdown
Size and alignment
markdown
{width=300} {width=80%} {width=4in} {fig-align="left"}
Alternative text and titles
markdown
{fig-alt="A drawing of an elephant."} {fig-alt="A drawing of an elephant."}
See Figure basics for more.
Advanced Formatting: Divs and Spans
Divs for block-level content:
markdown
::: {#ID .class attribute=value}
This is a "fenced div".
:::Spans for inline formatting:
markdown
[This is a "span"]{#ID .class attribute=value}See Divs and Spans for more.
Quarto Markdown
Enhanced Markdown Capabilities
Quarto extends standard markdown with powerful features designed specifically for computational documents.
Shortcodes
What is a Shortcode?
Shortcodes are special markdown directives that generate various types of content.
They provide a simple, standardised way to insert dynamic or complex content into your Quarto documents without requiring complex markdown syntax or HTML knowledge.
Built-in Shortcodes
| Shortcode | Description |
|---|---|
| version | Print Quarto CLI version. |
| var | Print value from _variables.yml file. |
| meta | Print value from document metadata. |
| env | Print system environment variable. |
| pagebreak | Insert a native page-break. |
| kbd | Describe keyboard shortcuts. |
| video | Embed a video in a document. |
| include | Include contents of another qmd. |
| embed | Embed cells from a Jupyter Notebook. |
| placeholder | Add placeholder images to your document. |
| lipsum | Add placeholder text to your document. |
| contents | Rearrange content in your document. |
The include Shortcode
Reuse content across multiple documents effortlessly:
markdown
{{< include _content.qmd >}}Key Benefits
- DRY Principle: Write once, use everywhere.
- Consistency: Shared content stays synchronised.
- Maintenance: Update in one place, changes propagate automatically.
- Modularity: Break complex documents into manageable pieces.
Common Use Cases
- Reusable code.
- Common configuration snippets.
Tip
Prefix your file or directory with an underscore (_) to hide from Quarto’s rendering process.
Important
The include shortcode is a plain copy-paste of the file content. Any YAML header in the included file will replace the current document’s YAML header.
Mermaid Diagrams
markdown
```{mermaid}
%%| label: quarto-mermaid-example-1
%%| fig-width: 5
flowchart LR
qmd --> J([Jupyter])
qmd --> K([knitr])
J --> md
K --> md
md --> P([pandoc])
P --> typst
P --> html
P --> docx
```flowchart LR qmd --> J([Jupyter]) qmd --> K([knitr]) J --> md K --> md md --> P([pandoc]) P --> pdf P --> html P --> docx
See Diagrams for more.
Callout Blocks
Five types of callouts for better communication: note, tip, warning, caution, important.
markdown
::: {.callout-note}
## Note
Important information for readers.
:::
::: {.callout-warning}
## Warning
Something to be careful about.
:::
NoteNote
Important information for readers.
WarningWarning
Something to be careful about.
See Callout Blocks for more.
Code Annotations
Source
markdown
```r library(tidyverse) library(palmerpenguins) penguins |> # <1> mutate( # <2> bill_ratio = bill_depth_mm / bill_length_mm, # <2> bill_area = bill_depth_mm * bill_length_mm # <2> ) # <2> ``` 1. Take `penguins`, and then, 2. add new columns for the bill ratio and bill area.
Output
r
- 1
-
Take
penguins, and then, - 2
- add new columns for the bill ratio and bill area.
See Code Annotation for more.
Cross-references: “figures”
markdown
::: {#fig-example}
This is a figure
This is a caption for the figure.
:::
@fig-example is the reference to a figure.
Or is it?This is a figure
Figure 1 is the reference to a figure.
Any label/ID starting with fig- will be treated as a figure cross-reference.
See Basic Cross-Reference - Figures for more.
Cross-references: “tables”
markdown
::: {#tbl-example}
This is a table
This is a caption for the table.
:::
@tbl-example is the reference to a table.
Or is it?This is a table
Table 2 is the reference to a table.
Any label/ID starting with tbl- will be treated as a table cross-reference.
See Basic Cross-Reference - Tables for more.
Cross-references: “anything”
Define a new custom cross-reference type:
- 1
-
Cross-referenceable elements with captions are
float. - 2
-
The identifier prefix used in labels (e.g.,
@txt-example). - 3
- The text prefix shown in output (e.g., “Text 1”).
markdown
::: {#txt-example}
This is text
This is a caption for the text.
:::
@txt-example is the reference to a text.This is text
Text 1 is the reference to a text.
See Custom Float Cross-Reference Types for more.
Citations
Setup Required
- Bibliography file (
.bib,.bibtex, etc.). - Optional: CSL file for custom styling.
YAML Configuration
yaml
bibliography: references.bib
csl: nature.csl # Optional custom styleBibliography Generation
- Automatic placement at document end.
- Use
## References {#refs}for custom placement. nocite: "@*"includes all references.
Citation Syntax
[@author2023]→ (Author 2023)[@author2023, p. 15]→ (Author 2023, 15)[@smith2020; @jones2021]→ (Smith 2020; Jones 2021)@author2023 says...→ Author (2023) says…[-@author2023]→ (2023) - suppress author
YAML Configuration
Overview
The YAML header serves as the configuration hub for your documents, controlling output formats, execution behaviour, and visual presentation.
Metadata Inheritance:
- Project level:
_quarto.yml(lowest priority). - Directory level:
_metadata.yml(medium priority). - Document level: YAML header (highest priority).
Multiple Metadata Files:
yaml
metadata-files:
- _website.yml
- _common.ymlDocument Header
yaml
- 1
- Common metadata fields. Option shared by all formats.
- 2
- Option specifically set for HTML output.
- 3
- Global options controlling code execution behaviour.
Multi-Format Output
Configure multiple output formats simultaneously and share options:
yaml
- 1
- Option shared by all formats.
- 2
- Option specifically set for PDF (LaTeX) output.
Extensions
TipInstalling the
highlight-text extension
Bash
quarto add mcanouil/quarto-highlight-text@2.0.1yaml
filters:
- highlight-textmarkdown
[White text, Blue background]{
colour="#FFFFFF" bg-colour="#0000FF"
}White text, Blue backgroundWhite text, Blue background
Discover more extensions at:
Hands-On Exercise: Building Your Quarto Portfolio Document
Exercise Overview
Objective: Enhance your Session 1 project with advanced Quarto markdown features, demonstrating authoring essentials and creating a comprehensive personal portfolio document.
Example Code:
bash
tar -xzf "02-exercises.tar.gz" -C "02-authoring-essentials"Part 1: Document Enhancement
Building on your Session 1 project, enhance your document with these new authoring features:
Create a new document with multi-format support:
Code
yaml
--- title: "My Quarto Learning Portfolio" author: "Your Name" date: today format: html: default typst: default ---
Add a numbered table of contents structured by using:
Code
markdown
### Learning Progress [New section - see Part 2] ### Skills Showcase [New section - see Part 3] ### Reflection & Next Steps [Your existing learning goals and next steps]
Part 2: Advanced Formatting Features
Add these enhanced markdown elements to your “Learning Progress” section:
Create a skills tracking table:
Code
markdown
## Learning Progress | Feature | Confidence Level | Notes | |---------|:---------------:|-------| | Basic Markdown | ⭐⭐⭐ | Comfortable with headers, lists | | YAML Configuration | ⭐⭐ | Learning multi-format setup | | Cross-references | ⭐ | Just discovered this! | : My Quarto Skills Progress {#tbl-skills} As shown in @tbl-skills, I'm making steady progress!
Add callout blocks for key insights:
Code
markdown
::: {.callout-tip} ## Today's Biggest Discovery I learned that Quarto can render to multiple formats simultaneously - this will revolutionise my workflow! ::: ::: {.callout-note collapse="true"} ## Session Notes - Enhanced markdown features are powerful - Cross-references work across formats - YAML controls everything! :::
Part 3: Skills Showcase Section
Create a “Skills Showcase” section demonstrating your new capabilities:
Mathematical expressions:
Code
markdown
## Skills Showcase ### Mathematical Typesetting I can now write inline maths like $E = mc^2$ and display equations: $$ \text{Learning Rate} = \frac{\text{New Concepts}}{\text{Practice Time}} $$Code blocks with annotations:
Code
markdown
### Code Documentation ```r # My first annotated code block library(ggplot2) # <1> data(mtcars) # <2> ggplot(mtcars, aes(x = mpg)) + # <3> geom_histogram() # <3> ``` 1. Load the plotting library 2. Use built-in dataset 3. Create a simple histogram
Cross-referenced figure:
Code
markdown
### Workflow Diagram ::: {#fig-workflow} ``` Learn → Practice → Apply → Teach ``` My Quarto learning workflow ::: @fig-workflow shows my approach to mastering new tools.Footnotes for additional context:
Code
markdown
This exercise builds on Session 1^[Where we learned project setup and IDE integration] and adds the authoring essentials from Session 2.
Part 4: Multi-Format Testing
Test your enhanced document:
Render to HTML
bash
quarto render your-document.qmd --to htmlTry PDF output
bash
quarto render your-document.qmd --to typstCompare the outputs
Success Criteria
✅ You’ve successfully completed the exercise if you can:
- Customise your existing project with YAML configuration.
- Implement cross-references with tables and figures.
- Use callout blocks effectively for highlighting information.
- Create annotated code blocks.
- Integrate mathematical expressions appropriately.
- Successfully render to multiple formats.
Reuse
Copyright
© 2026 Mickaël CANOUIL