# 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

   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

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

- 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