Using boilerplate with Quarto for Scientific Writing

Introduction

The boilerplate package is designed to streamline scientific writing in Quarto documents. This vignette demonstrates a complete workflow for using boilerplate to manage reusable text templates in your research papers.

Why Use boilerplate with Quarto?

Quarto is becoming the standard for reproducible scientific documents. The boilerplate package enhances Quarto workflows by:

Centralizing reusable text in version-controlled databases
Enabling consistent language across documents
Supporting collaborative workflows
Reducing errors through template reuse
Facilitating updates when methods change
Supporting both RDS and JSON formats for different use cases (see vignette("boilerplate-json-workflow"))

Setting Up a Quarto Project

Recommended Project Structure

my-research-project/
├── .boilerplate-data/          # boilerplate databases
├── manuscript/
│   ├── paper.qmd               # Main manuscript
│   ├── _methods.qmd            # Methods section
│   └── references.bib          # Bibliography (auto-copied)
└── .gitignore                  # Exclude backups

Initialise boilerplate

# Use a project-specific directory
# For this example, using a temporary directory
data_path <- file.path(tempdir(), "quarto_example")

# Initialise all databases
boilerplate_init(
  data_path = data_path,
  create_dirs = TRUE,
  create_empty = FALSE,  # Load default content
  confirm = FALSE,
  quiet = TRUE
)

Configure .gitignore

Add to your .gitignore:

# Exclude boilerplate backups
.boilerplate-data/*.bak

Building Your Text Database

Methods Templates

Create reusable methods templates with placeholders:

# Import database first
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

# Add participant recruitment template to the unified database
db <- boilerplate_add_entry(
  db,
  path = "methods.participants.recruitment",
  value = "We recruited {{n_participants}} participants through {{recruitment_method}}.",
  category = "methods"
)

# Save the updated database
boilerplate_save(db, data_path = data_path, confirm = FALSE, quiet = TRUE)

Measures Database

Store information about your measures:

# Add a measure to the unified database
db$measures$gad7 <- list(
  name = "GAD-7",
  description = "Generalized Anxiety Disorder 7-item scale",
  type = "ordinal",  # Required field
  items = list(
    "Feeling nervous, anxious, or on edge",
    "Not being able to stop or control worrying"
  ),
  reference = "@spitzer2006"
)

# Save the updated database
boilerplate_save(db, data_path = data_path, confirm = FALSE, quiet = TRUE)

Using Templates in Quarto

Here’s how to use boilerplate in your Quarto document:

# Import database (using the temp path from above)
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

# Generate methods text
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = "participants.recruitment",
  global_vars = list(
    n_participants = 250,
    recruitment_method = "online panels"
  ),
  db = db,
  quiet = TRUE
)

# Output: "We recruited 250 participants through online panels."

Example Quarto Document Structure

Your main Quarto document (paper.qmd) might look like:

---
title: "Your Research Paper"
author: "Your Name"
format: pdf
---

Then in the document:

## Introduction

[Your introduction...]

## Methods

{{< include _methods.qmd >}}

## Results

[Your results...]

And in _methods.qmd:

library(boilerplate)

# Load database and generate text
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

# Generate participant section
participant_text <- boilerplate_generate_text(
  category = "methods",
  sections = "participants.recruitment",
  global_vars = list(n_participants = 250),
  db = db
)

cat(participant_text)

Best Practices

Version Control: Commit your .boilerplate-data/*.rds files to git
Documentation: Document template variables in descriptions
Organization: Use hierarchical paths (e.g., methods.participants.recruitment)
Collaboration: Share databases through version control
Maintenance: Use batch operations to update multiple entries

Bibliography Management

The boilerplate package can manage your bibliography file, ensuring consistent citations across projects:

# Add bibliography information to your database
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

# Using the example bibliography included with the package
example_bib <- system.file("extdata", "example_references.bib", package = "boilerplate")
db <- boilerplate_add_bibliography(
  db,
  url = paste0("file://", example_bib),
  local_path = "references.bib"
)

# Save the updated database
boilerplate_save(db, data_path = data_path, confirm = FALSE, quiet = TRUE)

Automatic Bibliography Copying

When generating text, automatically copy the bibliography:

# Generate text and copy bibliography
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = "statistical.default",  # Use existing section
  db = db,
  copy_bibliography = TRUE,
  bibliography_path = "manuscript/"  # Copy to manuscript directory
)

Your Quarto document header would include:

---
title: "Your Paper"
bibliography: references.bib
---

Validating Citations

Ensure all citations in your boilerplate text exist in your bibliography:

# Validate references
validation <- boilerplate_validate_references(db)

if (!validation$valid) {
  warning("Missing references: ", paste(validation$missing, collapse = ", "))
}

Advanced Features

Batch Updates

Update multiple entries at once:

# Update all methods entries
db <- boilerplate_import(data_path = data_path, quiet = TRUE)

boilerplate_batch_edit(
  db = db$methods,
  field = "text",
  new_value = function(text) gsub("old text", "new text", text),
  target_entries = "*",
  preview = TRUE  # Preview changes first
)

Quarto Parameters

Use Quarto parameters with boilerplate:

---
params:
  n_participants: 250
  study_name: "Study 1"
---

Then in your code:

methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = "participants",
  global_vars = list(
    n_participants = params$n_participants,
    study_name = params$study_name
  ),
  db = db
)