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 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:

Component	Description
`frogs/`	Main project directory
`frogs.qmd`	Main Quarto document
`_quarto.yml`	Reusable project settings
`_variables.yml`	Reusable document settings
`_brand.yml`	Reusable brand style settings
`custom.scss`	Style sheet template
`dated_progress_notes.md`	Project documentation
`README.md`	Project documentation
`.gitignore`	Enhanced security settings
`references.bib`	Example citation template

Understanding Project Components

Each component serves a specific purpose:

Quarto Document (_quarto.yml)
- Pre-configured YAML to import _variables.yml
- Links to styling files
- Familiar format toggles

Project Settings (_variables.yml)

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

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
Style Sheet (custom.scss)
- Professional defaults
- Customizable elements
- Clear documentation

Individual Document Creation

Create a new Quarto document in an existing project: froggeR::write_quarto(). Use the example = TRUE to incorporate template cross-referencing, hyperlinks, and other useful Quarto writing tools.

Rendered Output

Example output of custom_yaml document

Note: This example uses a froggeR version pre-0.5.0 though the main heading will render the same… you get the point ;)

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
`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.

Additional Documents

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

froggeR::write_quarto(
  filename = "analysis"
)

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:

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 = "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.

YAML Additions

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

Style Variations
- Uncomment chosen lines in the custom.scss file (provided)
- 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 & _quarto.yml exist
- 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 ?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