Using boilerplate with Quarto for Scientific Writing

library(boilerplate)

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
data_path <- ".boilerplate-data"

# Initialise all databases
boilerplate_init(
  data_path = data_path,
  create_dirs = TRUE,
  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:

# Add participant recruitment template
boilerplate_add_entry(
  db_path = file.path(".boilerplate-data", "boilerplate_methods.rds"),
  category = "methods",
  path = "participants.recruitment",
  value = list(
    description = "Participant recruitment procedures",
    text = "We recruited {{n_participants}} participants through {{recruitment_method}}."
  ),
  confirm = FALSE
)

Measures Database

Store information about your measures:

# Add a measure
boilerplate_add_entry(
  db_path = file.path(".boilerplate-data", "boilerplate_measures.rds"),
  category = "measures",
  path = "anxiety.gad7",
  value = list(
    name = "GAD-7",
    description = "Generalized Anxiety Disorder 7-item scale",
    items = list(
      "Feeling nervous, anxious, or on edge",
      "Not being able to stop or control worrying"
    ),
    reference = "Spitzer et al. (2006)"
  ),
  confirm = FALSE
)

Using Templates in Quarto

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

# Import database
db <- boilerplate_import(data_path = ".boilerplate-data", 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(".boilerplate-data", 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

1. Version Control: Commit your .boilerplate-data/*.rds files to git
2. Documentation: Document template variables in descriptions
3. Organization: Use hierarchical paths (e.g., methods.participants.recruitment)
4. Collaboration: Share databases through version control
5. 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(".boilerplate-data", quiet = TRUE)

db <- boilerplate_add_bibliography(
  db,
  url = "https://raw.githubusercontent.com/go-bayes/templates/main/bib/references.bib",
  local_path = "references.bib"
)

# Save the updated database
boilerplate_save(db, data_path = ".boilerplate-data")

Automatic Bibliography Copying

When generating text, automatically copy the bibliography:

# Generate text and copy bibliography
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = "analysis.regression",
  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(".boilerplate-data", 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
)

Conclusion

The boilerplate package enhances Quarto workflows by providing a robust system for managing reusable text templates. This approach ensures consistency, reduces errors, and streamlines the scientific writing process.