Quarto Workflow with froggeR • froggeR

Introduction 🐸

froggeR streamlines your Quarto workflow by providing two powerful functions: quarto_project() for complete project initialization and write_quarto() for individual document creation. This vignette demonstrates how to use these functions effectively and how they work together.

Project Creation

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:

Component	Description
`frogs/`	Main project directory
`frogs.qmd`	Main Quarto document
`frogs.Rproj`	RStudio project file
`_variables.yml`	Reusable document settings
`custom.scss`	Style sheet template
`README.md`	Project documentation
`.gitignore`	Enhanced security settings

Understanding Project Components

Each component serves a specific purpose:

Quarto Document (frogs.qmd)
- Pre-configured YAML header
- Links to your styling
- Ready for content

Project Settings (_variables.yml)

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

Note: These values come from your froggeR_settings(). You can customize these settings by running froggeR::froggeR_settings() interactively. This function allows you to update author details, contact information, affiliations, and other document preferences. For more details, see ?froggeR_settings.

Style Sheet (custom.scss)
- Professional defaults
- Customizable elements
- Clear documentation

Integrated YAML structure example

Individual Document Creation

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:

Project Documents (custom_yaml = TRUE)
- Use project settings
- Include custom styling
- Maintain consistency
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.

Rendered Output

Example output of custom_yaml document

Workflow Integration

Project-Level Workflow

Best practices for project organization:

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

Additional Documents

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

froggeR::write_quarto(
  filename = "analysis",
  custom_yaml = TRUE
)

Project Structure

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

Document Management

Tips for effective document organization:

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

Common .gitignore patterns:

Pattern	Excludes	Why
`*.rds`	R data files	Data security
`.Rhistory`	R history files	Session cleanup
`output/`	Generated files	Avoid tracking outputs
`*.html`	Rendered documents	Focus on source files

Common Customizations

Project Modifications

Customize your project structure:

froggeR::quarto_project(
  name = "advanced_frogs",
  initialize_project = TRUE  # Include all styling options
)

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:

YAML Additions

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

Style Variations
- Create additional SCSS files
- Modify existing styles
- Add document-specific rules

Troubleshooting

Common issues and solutions:

Project Creation Issues
- Verify directory permissions
- Check for existing projects
- Ensure valid project name
Document Problems
- Confirm _variables.yml exists
- Check YAML syntax
- Verify file locations
Style Integration
- Review SCSS references
- Check file paths
- Validate YAML structure

Additional Resources

For more information on:

Quarto documents: vignette("customizing-quarto", package = "froggeR")
Project styling: See ?write_scss
Settings management: See ?froggeR_settings

Summary

froggeR’s project workflow provides:

Efficient project initialization
Consistent document creation
Integrated styling
Automated setup
Professional templates

Happy documenting! 🐸

Streamlined Quarto workflows with automated excellence