Communicating your research

Your first document, and your first article, in quarto

Arun Mitra

2026-09-10

What is Quarto?

An open-source publishing system
You write prose and code in one file
Quarto runs the code and puts the results in the document
One source becomes HTML, Word, PDF, slides, a website

It is the successor to R Markdown, and it works with R, Python and Julia.

Why bother?

You found one data entry error
The figure was pasted into Word
So was the number in the text, and the number in the table

If a number can be typed twice, it will eventually disagree with itself.

Let us dive in

File → New File → Quarto Document

Format: HTML, PDF, Word. Pick one; you can change it later
Title: anything
Click Create, then click Render

You now have a working document. Everything after this is editing.

Every `.qmd` has three parts

---
title: "Birth weight and maternal smoking"
author: "Your name"
format: html
---

## Background                          <- prose, in Markdown

Low birth weight is defined as under 2500 g.

```{r}                                 <- code, in a chunk
ggplot(births, aes(smoke, bwt)) +
  geom_boxplot()
```

YAML — the settings, fenced by ---. Title, author, output format.
Prose — plain Markdown. What you would have typed in Word.
Chunks — R code that runs when you render.

Markdown essentials

# Heading 1
## Heading 2

**bold** and _italics_

- a bullet
- another

1. numbered
2. list

> a quote

[a link](https://quarto.org)

Heading 1

Heading 2

bold and italics

a bullet
another

numbered
list

a quote

a link

Code chunks


::: {.cell}

```{.r .cell-code}
print("Hello from R!")
```

::: {.cell-output .cell-output-stdout}

```
[1] "Hello from R!"
```


:::

```{.r .cell-code}
1 + 2
```

::: {.cell-output .cell-output-stdout}

```
[1] 3
```


:::
:::

Click Run, and R executes the chunk right there in the document. Press Render, and every chunk runs in order, from a clean session.

Execution options control what appears


::: {.cell}
::: {.cell-output-display}
![Birth weight by maternal smoking.](index_files/figure-revealjs/fig-bwt-1.png){#fig-bwt width=960}
:::
:::

A name. fig- for a figure, tbl- for a table. Cross-references point here.
The caption. Numbered automatically.
Hide the code, show the output. What you want in a manuscript.
Suppress warnings in the output. Read them in the console instead.

Now, your first article

An article has a structure

## Introduction

## Rationale

## Objectives

## Methodology

## Results

## Discussion

## Conclusion

## References

Second-level headings ## for sections
Third-level ### for subsections
The table of contents builds itself
References appear on their own, at the end

Adding a figure — two ways

1. An image you already have

![MedEd Conclave](images/meded-logo.png)

2. A figure R makes for you


::: {.cell}

```{.r .cell-code}
ggplot(births, aes(smoke, bwt)) +
  geom_boxplot()
```

::: {.cell-output-display}
![Birth weight by smoking.](index_files/figure-revealjs/unnamed-chunk-3-1.png){width=960}
:::
:::

Width and alignment:

![](logo.png){width=50%
              fig-align="left"}

Cross-references

![Birth weight by smoking](fig.png){#fig-bwt}

This is illustrated well by @fig-bwt.

Renders as: “This is illustrated well by Figure 1.”

Two rules, and both are silent when broken:

The label must start fig- or tbl-
The reference is @ plus that exact label

Adding a table — two ways

1. Typed in Markdown

| Group | n | Mean |
|-------|--:|-----:|
| Non-smoker | 115 | 3056 |
| Smoker | 74 | 2772 |

: Birth weight by group

2. Computed from the data


::: {#tbl-one .cell tbl-cap='Characteristics.'}

```{.r .cell-code}
births |>
  select(smoke, age, bwt) |>
  tbl_summary(by = smoke)
```

::: {.cell-output-display}

```{=html}
<div id="rzrdsihqdv" style="padding-left:0px;padding-right:0px;padding-top:10px;padding-bottom:10px;overflow-x:auto;overflow-y:auto;width:auto;height:auto;">
<style>#rzrdsihqdv table {
  font-family: system-ui, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

#rzrdsihqdv thead, #rzrdsihqdv tbody, #rzrdsihqdv tfoot, #rzrdsihqdv tr, #rzrdsihqdv td, #rzrdsihqdv th {
  border-style: none;
}

#rzrdsihqdv p {
  margin: 0;
  padding: 0;
}

#rzrdsihqdv .gt_table {
  display: table;
  border-collapse: collapse;
  line-height: normal;
  margin-left: auto;
  margin-right: auto;
  color: #333333;
  font-size: 16px;
  font-weight: normal;
  font-style: normal;
  background-color: #FFFFFF;
  width: auto;
  border-top-style: solid;
  border-top-width: 2px;
  border-top-color: #A8A8A8;
  border-right-style: none;
  border-right-width: 2px;
  border-right-color: #D3D3D3;
  border-bottom-style: solid;
  border-bottom-width: 2px;
  border-bottom-color: #A8A8A8;
  border-left-style: none;
  border-left-width: 2px;
  border-left-color: #D3D3D3;
}

#rzrdsihqdv .gt_caption {
  padding-top: 4px;
  padding-bottom: 4px;
}

#rzrdsihqdv .gt_title {
  color: #333333;
  font-size: 125%;
  font-weight: initial;
  padding-top: 4px;
  padding-bottom: 4px;
  padding-left: 5px;
  padding-right: 5px;
  border-bottom-color: #FFFFFF;
  border-bottom-width: 0;
}

#rzrdsihqdv .gt_subtitle {
  color: #333333;
  font-size: 85%;
  font-weight: initial;
  padding-top: 3px;
  padding-bottom: 5px;
  padding-left: 5px;
  padding-right: 5px;
  border-top-color: #FFFFFF;
  border-top-width: 0;
}

#rzrdsihqdv .gt_heading {
  background-color: #FFFFFF;
  text-align: center;
  border-bottom-color: #FFFFFF;
  border-left-style: none;
  border-left-width: 1px;
  border-left-color: #D3D3D3;
  border-right-style: none;
  border-right-width: 1px;
  border-right-color: #D3D3D3;
}

#rzrdsihqdv .gt_bottom_border {
  border-bottom-style: solid;
  border-bottom-width: 2px;
  border-bottom-color: #D3D3D3;
}

#rzrdsihqdv .gt_col_headings {
  border-top-style: solid;
  border-top-width: 2px;
  border-top-color: #D3D3D3;
  border-bottom-style: solid;
  border-bottom-width: 2px;
  border-bottom-color: #D3D3D3;
  border-left-style: none;
  border-left-width: 1px;
  border-left-color: #D3D3D3;
  border-right-style: none;
  border-right-width: 1px;
  border-right-color: #D3D3D3;
}

#rzrdsihqdv .gt_col_heading {
  color: #333333;
  background-color: #FFFFFF;
  font-size: 100%;
  font-weight: normal;
  text-transform: inherit;
  border-left-style: none;
  border-left-width: 1px;
  border-left-color: #D3D3D3;
  border-right-style: none;
  border-right-width: 1px;
  border-right-color: #D3D3D3;
  vertical-align: bottom;
  padding-top: 5px;
  padding-bottom: 6px;
  padding-left: 5px;
  padding-right: 5px;
  overflow-x: hidden;
}

#rzrdsihqdv .gt_column_spanner_outer {
  color: #333333;
  background-color: #FFFFFF;
  font-size: 100%;
  font-weight: normal;
  text-transform: inherit;
  padding-top: 0;
  padding-bottom: 0;
  padding-left: 4px;
  padding-right: 4px;
}

#rzrdsihqdv .gt_column_spanner_outer:first-child {
  padding-left: 0;
}

#rzrdsihqdv .gt_column_spanner_outer:last-child {
  padding-right: 0;
}

#rzrdsihqdv .gt_column_spanner {
  border-bottom-style: solid;
  border-bottom-width: 2px;
  border-bottom-color: #D3D3D3;
  vertical-align: bottom;
  padding-top: 5px;
  padding-bottom: 5px;
  overflow-x: hidden;
  display: inline-block;
  width: 100%;
}

#rzrdsihqdv .gt_spanner_row {
  border-bottom-style: hidden;
}

#rzrdsihqdv .gt_group_heading {
  padding-top: 8px;
  padding-bottom: 8px;
  padding-left: 5px;
  padding-right: 5px;
  color: #333333;
  background-color: #FFFFFF;
  font-size: 100%;
  font-weight: initial;
  text-transform: inherit;
  border-top-style: solid;
  border-top-width: 2px;
  border-top-color: #D3D3D3;
  border-bottom-style: solid;
  border-bottom-width: 2px;
  border-bottom-color: #D3D3D3;
  border-left-style: none;
  border-left-width: 1px;
  border-left-color: #D3D3D3;
  border-right-style: none;
  border-right-width: 1px;
  border-right-color: #D3D3D3;
  vertical-align: middle;
  text-align: left;
}

#rzrdsihqdv .gt_empty_group_heading {
  padding: 0.5px;
  color: #333333;
  background-color: #FFFFFF;
  font-size: 100%;
  font-weight: initial;
  border-top-style: solid;
  border-top-width: 2px;
  border-top-color: #D3D3D3;
  border-bottom-style: solid;
  border-bottom-width: 2px;
  border-bottom-color: #D3D3D3;
  vertical-align: middle;
}

#rzrdsihqdv .gt_from_md > :first-child {
  margin-top: 0;
}

#rzrdsihqdv .gt_from_md > :last-child {
  margin-bottom: 0;
}

#rzrdsihqdv .gt_row {
  padding-top: 8px;
  padding-bottom: 8px;
  padding-left: 5px;
  padding-right: 5px;
  margin: 10px;
  border-top-style: solid;
  border-top-width: 1px;
  border-top-color: #D3D3D3;
  border-left-style: none;
  border-left-width: 1px;
  border-left-color: #D3D3D3;
  border-right-style: none;
  border-right-width: 1px;
  border-right-color: #D3D3D3;
  vertical-align: middle;
  overflow-x: hidden;
}

#rzrdsihqdv .gt_stub {
  color: #333333;
  background-color: #FFFFFF;
  font-size: 100%;
  font-weight: initial;
  text-transform: inherit;
  border-right-style: solid;
  border-right-width: 2px;
  border-right-color: #D3D3D3;
  padding-left: 5px;
  padding-right: 5px;
}

#rzrdsihqdv .gt_stub_row_group {
  color: #333333;
  background-color: #FFFFFF;
  font-size: 100%;
  font-weight: initial;
  text-transform: inherit;
  border-right-style: solid;
  border-right-width: 2px;
  border-right-color: #D3D3D3;
  padding-left: 5px;
  padding-right: 5px;
  vertical-align: top;
}

#rzrdsihqdv .gt_row_group_first td {
  border-top-width: 2px;
}

#rzrdsihqdv .gt_row_group_first th {
  border-top-width: 2px;
}

#rzrdsihqdv .gt_summary_row {
  color: #333333;
  background-color: #FFFFFF;
  text-transform: inherit;
  padding-top: 8px;
  padding-bottom: 8px;
  padding-left: 5px;
  padding-right: 5px;
}

#rzrdsihqdv .gt_first_summary_row {
  border-top-style: solid;
  border-top-color: #D3D3D3;
}

#rzrdsihqdv .gt_first_summary_row.thick {
  border-top-width: 2px;
}

#rzrdsihqdv .gt_last_summary_row {
  padding-top: 8px;
  padding-bottom: 8px;
  padding-left: 5px;
  padding-right: 5px;
  border-bottom-style: solid;
  border-bottom-width: 2px;
  border-bottom-color: #D3D3D3;
}

#rzrdsihqdv .gt_grand_summary_row {
  color: #333333;
  background-color: #FFFFFF;
  text-transform: inherit;
  padding-top: 8px;
  padding-bottom: 8px;
  padding-left: 5px;
  padding-right: 5px;
}

#rzrdsihqdv .gt_first_grand_summary_row {
  padding-top: 8px;
  padding-bottom: 8px;
  padding-left: 5px;
  padding-right: 5px;
  border-top-style: double;
  border-top-width: 6px;
  border-top-color: #D3D3D3;
}

#rzrdsihqdv .gt_last_grand_summary_row_top {
  padding-top: 8px;
  padding-bottom: 8px;
  padding-left: 5px;
  padding-right: 5px;
  border-bottom-style: double;
  border-bottom-width: 6px;
  border-bottom-color: #D3D3D3;
}

#rzrdsihqdv .gt_striped {
  background-color: rgba(128, 128, 128, 0.05);
}

#rzrdsihqdv .gt_table_body {
  border-top-style: solid;
  border-top-width: 2px;
  border-top-color: #D3D3D3;
  border-bottom-style: solid;
  border-bottom-width: 2px;
  border-bottom-color: #D3D3D3;
}

#rzrdsihqdv .gt_footnotes {
  color: #333333;
  background-color: #FFFFFF;
  border-bottom-style: none;
  border-bottom-width: 2px;
  border-bottom-color: #D3D3D3;
  border-left-style: none;
  border-left-width: 2px;
  border-left-color: #D3D3D3;
  border-right-style: none;
  border-right-width: 2px;
  border-right-color: #D3D3D3;
}

#rzrdsihqdv .gt_footnote {
  margin: 0px;
  font-size: 90%;
  padding-top: 4px;
  padding-bottom: 4px;
  padding-left: 5px;
  padding-right: 5px;
}

#rzrdsihqdv .gt_sourcenotes {
  color: #333333;
  background-color: #FFFFFF;
  border-bottom-style: none;
  border-bottom-width: 2px;
  border-bottom-color: #D3D3D3;
  border-left-style: none;
  border-left-width: 2px;
  border-left-color: #D3D3D3;
  border-right-style: none;
  border-right-width: 2px;
  border-right-color: #D3D3D3;
}

#rzrdsihqdv .gt_sourcenote {
  font-size: 90%;
  padding-top: 4px;
  padding-bottom: 4px;
  padding-left: 5px;
  padding-right: 5px;
}

#rzrdsihqdv .gt_left {
  text-align: left;
}

#rzrdsihqdv .gt_center {
  text-align: center;
}

#rzrdsihqdv .gt_right {
  text-align: right;
  font-variant-numeric: tabular-nums;
}

#rzrdsihqdv .gt_font_normal {
  font-weight: normal;
}

#rzrdsihqdv .gt_font_bold {
  font-weight: bold;
}

#rzrdsihqdv .gt_font_italic {
  font-style: italic;
}

#rzrdsihqdv .gt_super {
  font-size: 65%;
}

#rzrdsihqdv .gt_footnote_marks {
  font-size: 75%;
  vertical-align: 0.4em;
  position: initial;
}

#rzrdsihqdv .gt_asterisk {
  font-size: 100%;
  vertical-align: 0;
}

#rzrdsihqdv .gt_indent_1 {
  text-indent: 5px;
}

#rzrdsihqdv .gt_indent_2 {
  text-indent: 10px;
}

#rzrdsihqdv .gt_indent_3 {
  text-indent: 15px;
}

#rzrdsihqdv .gt_indent_4 {
  text-indent: 20px;
}

#rzrdsihqdv .gt_indent_5 {
  text-indent: 25px;
}

#rzrdsihqdv .katex-display {
  display: inline-flex !important;
  margin-bottom: 0.75em !important;
}

#rzrdsihqdv div.Reactable > div.rt-table > div.rt-thead > div.rt-tr.rt-tr-group-header > div.rt-th-group:after {
  height: 0px !important;
}
</style>
<table class="gt_table" data-quarto-disable-processing="false" data-quarto-bootstrap="false">
  <thead>
    <tr class="gt_col_headings">
      <th class="gt_col_heading gt_columns_bottom_border gt_left" rowspan="1" colspan="1" scope="col" id="label"><span data-qmd-base64="KipDaGFyYWN0ZXJpc3RpYyoq"><span class='gt_from_md'><strong>Characteristic</strong></span></span></th>
      <th class="gt_col_heading gt_columns_bottom_border gt_center" rowspan="1" colspan="1" scope="col" id="stat_1"><span data-qmd-base64="KipOb24tc21va2VyKiogIApOID0gMTE1"><span class='gt_from_md'><strong>Non-smoker</strong><br />
N = 115</span></span><span class="gt_footnote_marks" style="white-space:nowrap;font-style:italic;font-weight:normal;line-height:0;"><sup>1</sup></span></th>
      <th class="gt_col_heading gt_columns_bottom_border gt_center" rowspan="1" colspan="1" scope="col" id="stat_2"><span data-qmd-base64="KipTbW9rZXIqKiAgCk4gPSA3NA=="><span class='gt_from_md'><strong>Smoker</strong><br />
N = 74</span></span><span class="gt_footnote_marks" style="white-space:nowrap;font-style:italic;font-weight:normal;line-height:0;"><sup>1</sup></span></th>
    </tr>
  </thead>
  <tbody class="gt_table_body">
    <tr><td headers="label" class="gt_row gt_left">age</td>
<td headers="stat_1" class="gt_row gt_center">23.0 (20.0, 26.0)</td>
<td headers="stat_2" class="gt_row gt_center">22.0 (19.0, 26.0)</td></tr>
    <tr><td headers="label" class="gt_row gt_left">bwt</td>
<td headers="stat_1" class="gt_row gt_center">3,100 (2,495, 3,629)</td>
<td headers="stat_2" class="gt_row gt_center">2,776 (2,367, 3,260)</td></tr>
  </tbody>
  <tfoot>
    <tr class="gt_footnotes">
      <td class="gt_footnote" colspan="3"><span class="gt_footnote_marks" style="white-space:nowrap;font-style:italic;font-weight:normal;line-height:0;"><sup>1</sup></span> <span data-qmd-base64="TWVkaWFuIChRMSwgUTMp"><span class='gt_from_md'>Median (Q1, Q3)</span></span></td>
    </tr>
  </tfoot>
</table>
</div>
```

:::
:::

Method 2 again is the one that cannot disagree with your data.

References and a bibliography

Low birth weight remains a leading cause of
neonatal mortality [@hosmer2013].

Keys come from a .bib file — Zotero and Mendeley both export one
bibliography: references.bib in the YAML
The reference list builds itself, at the end
csl: sets the style. Change journals, change one line

It does not stop at a document

An article

format: html · docx · pdf

A rendered document

Prose, code and the computed table in one file

Slides

format: revealjs — including these

A website

project: type: website — the workshop site

A book, or a thesis

project: type: book — seven chapters, one bibliography

A dashboard

format: dashboard — regenerated when new data arrive

R in the reader’s browser

format: live-html — the prelude primers

A PDF without LaTeX

format: typst

Hands-on — 45 min

Four exercises on the website.

Split your document with include
Add citations from a .bib
Cross-reference a table and a figure
(stretch) Render to Word, then publish

Green sticky when your document renders.