The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Quarto Workflow with 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:

  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
    variables dot yml
    Project metadata
  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

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

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:

  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:

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.

  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

Troubleshooting

Common issues and solutions:

  1. Project Creation Issues
    • Verify directory permissions
    • Check for existing projects
    • Ensure valid project name
  2. Document Problems
    • Confirm _variables.yml & _quarto.yml exist
    • Check YAML syntax
    • Verify file locations
  3. Style Integration
    • Review SCSS references
    • Check file paths
    • Validate YAML structure

Additional Resources

For more information on:


Summary

froggeR’s project workflow provides:

Happy documenting! 🐸


Streamlined Quarto workflows with automated excellence

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.