---
title: "Quarto Workflow with froggeR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Quarto Workflow with froggeR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

froggeR streamlines your Quarto workflow by providing two powerful functions: [`quarto_project()`](https://azimuth-project.tech/froggeR/reference/quarto_project.html) for complete project initialization and [`write_quarto()`](https://azimuth-project.tech/froggeR/reference/write_quarto.html) 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:

```r
>> 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`)

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

    <div style="text-align: center;">
      <figure>
        <img src="../man/figures/variables-yml.png" alt="variables dot yml" width="70%">
        <figcaption>Project metadata</figcaption>
      </figure>
    </div>


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

```{r, echo=FALSE, fig.align='center', fig.cap='Example output of custom_yaml document', out.width='85%'}
knitr::include_graphics("../man/figures/custom-yaml-rendered.png")
```

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

    ```{r, eval=FALSE}
    # 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**

    ```{r, eval=FALSE}
    # 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:

```{r, eval=FALSE}
froggeR::quarto_project(name = "my_project")
```

Then add specialized documents:

```{r, eval=FALSE}
# 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**

    ```yaml
    ---
    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*