Quarto Workflow with froggeR

Complete Project Setup

The quickest way to start a new Quarto project:

froggeR::quarto_project(name = "frogs")

This single command creates a complete project structure:

Your new project includes:

Understanding Project Components

Each component serves a specific purpose:

1. Quarto Document (frogs.qmd)

   • Pre-configured YAML header
   • Links to your styling
   • Ready for content

2. Project Settings (_variables.yml)

   author: Your Name
   email: your.email@example.com
   affiliations: Your Institution

   

3. Style Sheet (custom.scss)

   • Professional defaults
   • Customizable elements
   • Clear documentation

Basic Document

Create a new Quarto document in an existing project:

froggeR::write_quarto(
  filename = "frog_analysis",
  custom_yaml = TRUE  # Use settings from _variables.yml
)

This creates frog_analysis.qmd with:

• Formatted YAML header
• Two starter sections
• Links to project styling

Custom Documents

For documents without project settings and requiring manual changes to the document YAML:

froggeR::write_quarto(
  filename = "frog_standalone",
  custom_yaml = FALSE  # Basic Quarto template
)

Document Types

write_quarto() supports two main workflows:

1. Project Documents (custom_yaml = TRUE)
   • Use project settings
   • Include custom styling
   • Maintain consistency
2. Standalone Documents (custom_yaml = FALSE)
   • Basic Quarto template
   • No external dependencies
   • Quick start for simple docs

Comparison of document types

The custom_yaml = TRUE template leverages your project’s _variables.yml settings, automatically populating author information, styling, and other metadata. This means you can focus immediately on content creation rather than document setup. Conversely, custom_yaml = FALSE provides a minimal template when you need a standalone document without project-specific configurations.

Project-Level Workflow

Best practices for project organization:

1. Initial Setup

   # Create new project
   froggeR::quarto_project(name = "frogs")

   Recommended project structure:

   Directory/File	Purpose	Contents
   data/	Raw data storage	Input files, datasets
   output/	Analysis results	Figures, tables, exports
   R/	Custom functions	R scripts, utilities
   docs/	Documentation	Additional guides, notes
   *.qmd**	Analysis documents	Main content and code

   ** This is provided from froggeR::quarto_project(). All others need to be created.

2. Additional Documents

   # Add analysis documents
   froggeR::write_quarto(
     filename = "data_prep",
     custom_yaml = TRUE
   )
   
   froggeR::write_quarto(
     filename = "frogs",
     custom_yaml = TRUE
   )

3. Project Structure

   frogs/
   ├── frogs.qmd
   ├── data_prep.qmd
   ├── analysis.qmd
   ├── _variables.yml
   ├── custom.scss
   ├── dated_progress_notes.md
   └── README.md

Document Management

Tips for effective document organization:

1. Consistent Naming
   • Use descriptive filenames
   • Follow a naming convention
   • Consider document order
2. Settings Management
   • Keep _variables.yml updated
   • Maintain consistent styling
   • Document customizations
3. Version Control
   • Commit regularly
   • Update README
   • Track progress

Common .gitignore patterns:

Project Modifications

Customize your project structure:

froggeR::quarto_project(name = "advanced_frogs")

Then add specialized documents:

# Data preparation
froggeR::write_quarto(filename = "01_data_prep")

# Analysis
froggeR::write_quarto(filename = "02_analysis")

# Results
froggeR::write_quarto(filename = "03_results")

Note: When working in a froggeR project, write_quarto() automatically uses your project’s _variables.yml settings by default, ensuring consistent styling and metadata across all documents.

Document Customization

Modify individual documents while maintaining project consistency:

1. YAML Additions

   ---
   title: "Analysis Results"
   author: "{{{< var author >}}}"
   date: last-modified
   format:
     html:
       code-fold: true
       toc: true
   ---

2. Style Variations

   • Uncomment chosen lines in the custom.scss file (provided)
   • Modify existing styles
   • Add document-specific rules