Quarto Workflow with froggeR

Complete Project Setup

The quickest way to start a new Quarto project:

>> froggeR::quarto_project(name = "frogs")
This will create a new Quarto default project as a folder named frogs in
/home/kyle.
Do you want to proceed (Y/n)? 
Y
✔ Created Quarto project directory: frogs
✔ Created _quarto.yml
ℹ Copying existing froggeR settings...
✔ Created _variables.yml
ℹ Copying existing froggeR brand settings...
✔ Created _brand.yml
✔ Copying existing froggeR logos.
✔ Created custom.scss
✔ Created .gitignore
✔ Created README.md
✔ Created dated_progress_notes.md
✔ Created frogs.qmd with examples
✔ Created references.bib
✔ froggeR project setup complete. Opening in new session...

This single command creates a complete project structure:

Understanding Project Components

Each component serves a specific purpose:

1. Quarto Document (_quarto.yml)

   • Pre-configured YAML to import _variables.yml
   • Links to styling files
   • Familiar format toggles

2. Project Settings (_variables.yml)

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

   

3. Brand Settings (new for froggeR v0.5.0; _brand.yml)

   • Preconfigured branding file
   • Examples for adding logo, color, & typography
   • Save your personal or team art in the logos/ directory
   • Add a consistent style across your Quarto documents

4. Style Sheet (custom.scss)

   • Professional defaults
   • Customizable elements
   • Clear documentation

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
   logos/	Brand logos	Storing Quarto brand art
   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"
   )
   
   froggeR::write_quarto(
     filename = "analysis"
   )

3. Project Structure

   frogs/
   ├── frogs.qmd
   ├── data_prep.qmd
   ├── analysis.qmd
   ├── _brand.yml
   ├── _quarto.yml
   ├── _variables.yml
   ├── custom.scss
   ├── dated_progress_notes.md
   ├── references.bib
   └── 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 = "my_project")

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. In other words, the document-level YAML structure takes precedence and will override project-level settings found in _variables.yml and _quarto.yml.

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