Exercise: Write a Reproducible Manuscript

Learning Goal

Build a real Quarto manuscript project: a single source that renders to both a web article (HTML) and a journal-styled PDF, with full author metadata, a figure drawn from data, summary numbers pulled straight from that data, and a citation. Along the way you will see how project: type: manuscript turns one folder into a small scholarly publishing pipeline.

This is the hands-on companion to the Writing Manuscripts page. The full reference for everything below is the Quarto manuscript authoring guide.

Two Ways to Do This Exercise

Pick whichever is more useful to you — the steps are the same either way:

Path A — Bring your own. Take a current or previous research project or manuscript of your own and rebuild its skeleton as a Quarto manuscript. You will get the most out of the exercise this way, because you end with something you can actually keep working on.
Path B — Use our sample data. Build a mock manuscript about ecological restoration from the two datasets below. Choose this if you would rather not wrangle your own data right now.

Wherever a step needs concrete code, we show it for the sample data. If you are on Path A, swap in your own file names, columns, and text.

The Sample Data (Path B)

restoration-sites.csv records quarterly monitoring of four restoration sites. Each row is one survey of one site:

site — the monitoring site (A–D)
date — survey date (quarterly)
vegetation_cover_pct — vegetation cover, in percent
species_richness — number of species recorded
soil_moisture_pct — soil moisture, in percent

Download restoration-sites.csv Download restoration-scenarios.csv

(restoration-scenarios.csv holds vegetation cover under three management scenarios and is only needed for the stretch task.)

Step 1 — Create the Manuscript Project

A manuscript is a project, not a single file, so let Quarto scaffold the folder for you. In your terminal, move to wherever you keep projects and run:

quarto create project manuscript my-manuscript

This makes a folder my-manuscript/ with the basic structure a manuscript needs:

index.qmd — the article itself: metadata, narrative text, and code, all in one file.
_quarto.yml — project settings. The line project: type: manuscript is what tells Quarto to treat this folder as a manuscript and build the article website.
references.bib — your bibliography. Citations you add land here automatically.
notebooks/ — optional extra computational notebooks you can link from the article.

Prefer buttons to typing?

You don’t have to use the terminal. In RStudio choose New Project → Quarto Manuscript; in Positron or VS Code open the command palette and pick Quarto: Create Project → Manuscript Project. The result is the same starter folder.

Open the folder in your editor and switch index.qmd to the visual editor (the Source / Visual toggle in RStudio or Positron) — it makes adding authors, figures, and citations much easier in the steps below.

A note on the code chunks below

Every R chunk in your real index.qmd opens with ```{r} — with curly braces — so Quarto runs it. In the sketches on this page we write ```r without braces only so they display as text instead of executing. When you copy them into your file, add the braces back.

Step 2 — Add Your Authors

Open index.qmd. Replace the starter front matter with your own title and a proper author block. Add yourself and one co-author — pick a real colleague — each with an ORCID, email, and affiliation. This is the scholarly metadata Quarto uses to build the byline and, later, the journal PDF.

---
title: "Vegetation Recovery Across Four Restoration Sites"
author:
  - name: Your Name
    orcid: 0000-0000-0000-0000
    corresponding: true
    email: you@institute.org
    affiliations:
      - name: Your Institute
        department: Department of Ecology
        city: Your City
        country: Your Country
  - name: A Colleague
    orcid: 0000-0000-0000-0001
    corresponding: false
    affiliations:
      - name: Their Institute
        department: Department of Soil Science
date: today
bibliography: references.bib
---

Where to find an ORCID

Every researcher can register for a free ORCID at orcid.org — it is the 16-digit ID in their profile URL. Use real ones if you have them; the placeholders above will still render fine.

Step 3 — Choose and Apply a Journal Template

The point of a manuscript is to produce a journal-ready document. Quarto maintains a set of journal templates at github.com/quarto-journals — including Elsevier, PLOS, ACS (American Chemical Society), AGU (American Geophysical Union), ACM, and JSS.

Add one to your project from inside the my-manuscript/ folder. We’ll use Elsevier as a general-purpose example:

quarto add quarto-journals/elsevier

This installs an extension that provides a new format, elsevier-pdf. Now tell the manuscript to build both the web article and the journal PDF by editing the format: block in _quarto.yml:

project:
  type: manuscript

format:
  html: default
  elsevier-pdf: default

html is the article webpage; elsevier-pdf is the typeset PDF. Each journal extension names its formats after the journal — swap in plos-pdf, acs-pdf, agu-pdf, and so on if you install a different one.

PDF needs a LaTeX engine

The first time you render a PDF, Quarto needs LaTeX. Install the lightweight bundle it manages for you, once, with:

quarto install tinytex

If you’d rather skip the journal extension for now, the built-in pdf: default format also works and needs the same TinyTeX install.

Step 4 — Load Your Data in a Setup Chunk

Make a data/ folder inside my-manuscript/ and copy restoration-sites.csv into it (use the download button above). Then add a setup chunk near the top of index.qmd, below the front matter. include: false runs the code but keeps it and its output out of the article:

```r
#| label: setup
#| include: false

library(readr)
library(dplyr)
library(ggplot2)

sites <- read_csv("data/restoration-sites.csv") |>
  mutate(date = as.Date(date))

latest <- sites |> filter(date == max(date))   # most recent survey per site
first  <- sites |> filter(date == min(date))   # earliest survey per site
```

latest and first give us the start and end of the monitoring period, which the next two steps use.

Step 5 — Pull Summary Numbers Into Your Text With Inline Code

This is where a reproducible manuscript earns its keep: numbers in the prose come from the data, so they can never drift out of sync with it. Inline R code uses single backticks, `r expr`. Write an opening paragraph like this:

We monitored vegetation recovery at `r n_distinct(sites$site)` restoration
sites across `r n_distinct(sites$date)` quarterly surveys. Mean vegetation
cover rose from `r round(mean(first$vegetation_cover_pct))`% at the first
survey to `r round(mean(latest$vegetation_cover_pct))`% at the most recent —
an increase of `r round(mean(latest$vegetation_cover_pct) - mean(first$vegetation_cover_pct))`
percentage points.

When rendered, the backticked expressions become real values (4 sites, 8 surveys, and so on). Change the CSV and the sentence updates itself.

Step 6 — Add a Figure From Code

Add a code chunk that draws a ggplot figure. The fig- prefix on the label makes it cross-referenceable, and fig-cap gives it a numbered caption:

```r
#| label: fig-cover
#| fig-cap: "Vegetation cover at four restoration sites, quarterly 2023–2025."

ggplot(sites, aes(date, vegetation_cover_pct, colour = site)) +
  geom_line() +
  geom_point() +
  labs(x = NULL, y = "Vegetation cover (%)", colour = "Site") +
  theme_minimal()
```

Then refer to it in your text. Quarto turns @fig-cover into “Figure 1” and links to it:

Cover increased at every site over the monitoring period (@fig-cover).

Step 7 — Add a Citation

In the visual editor, put your cursor where the citation should go and choose Insert → Citation. The dialog can pull references straight from a DOI or from your Zotero library (as well as Crossref, PubMed, and DataCite):

From a DOI: paste a DOI and Quarto fetches the full reference. For example, try 10.1111/rec.13035 (the SER international standards for ecological restoration).
From Zotero: if you have Zotero installed and the integration enabled, search your own library by author or title.

Either way, Quarto inserts an @citation-key in your text, appends the entry to references.bib, and adds a formatted reference list at the end on render. A sentence like:

Our monitoring follows recognised restoration standards [@gann2019].

renders the citation in text and the full reference under a References heading.

Switching citation styles

references.bib stores the facts; a CSL style decides the formatting. To format references for a specific journal, add a csl: line to your front matter pointing at a style file (browse thousands at the Zotero Style Repository). No re-typing required.

Step 8 — Render to PDF and HTML

You now have everything the seven previous steps promised. Build all formats at once:

quarto render

Or, while writing, run quarto preview for a live HTML view that refreshes on every save. Open the rendered article (_manuscript/ or the preview): it shows your byline, the inline numbers, the figure, and the references. In the margin, an Other Formats section now offers a download link to your Elsevier PDF — one source, two outputs.

What just happened

quarto render ran your R code once, injected the results into the text and the figure, and laid the same content out twice: as a web page and as a typeset PDF. That single-source, multi-format render is the whole reason to write a manuscript in Quarto.

Stretch Tasks

If you finish early, try one of these:

Add an abstract and keywords to the front matter (abstract: | and keywords:) and see them appear in both outputs.
Add a table from the data — for example the latest reading per site with knitr::kable() — give it a #| label: tbl- and cross-reference it with @tbl-....
Compare scenarios. Read restoration-scenarios.csv and add a second figure faceted or coloured by scenario (Baseline / Moderate / Intensive).
Add a Word output for collaborators who want track-changes: add docx: default to the format: block and render again.

Adapting Path A (Your Own Manuscript)

Converting your own work follows exactly the same skeleton:

Paste your existing prose into index.qmd under Introduction / Methods / Results / Discussion headings.
Drop your data into data/ and your analysis into the setup chunk (or source() a separate script — see the tip on the Writing Manuscripts page).
Replace every hard-typed statistic in your Results with inline `r ...` code.
Re-create your key figure as a labelled code chunk and cross-reference it.
Import your existing .bib (or pull citations from Zotero) and cite with @key.

Self-Check

Does quarto render produce both an HTML article and a PDF without errors?
Does the byline show you and your co-author, with ORCIDs and affiliations?
Do the numbers in your opening paragraph come from inline code, not typed by hand?
Does @fig-cover render as a numbered, clickable “Figure 1”?
Does your citation appear in the text and in a References list, with the entry now in references.bib?