---
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://kylegrealis.github.io/froggeR/reference/quarto_project.html) for complete project initialization and [`write_quarto()`](https://kylegrealis.github.io/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, eval=FALSE}
froggeR::quarto_project(name = "frogs")
```

This single command creates a complete project structure:

<div style="text-align: center;">
  <figure>
    <img src="../man/figures/froggeR-init.png" alt="Project initialization example" width="70%">
    <figcaption>Project initialization example</figcaption>
  </figure>
</div>

<div style="text-align: center;">
  <figure>
    <img src="../man/figures/new-froggeR-session.png" alt="Project directory structure example" width="70%">
    <figcaption>Project directory structure example</figcaption>
  </figure>
</div>

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 |
| `dated_progress_notes.md` | Project documentation |
| `README.md` | Project documentation |
| `.gitignore` | Enhanced security settings |

### Understanding Project Components

Each component serves a specific purpose:

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


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

----

## Individual Document Creation

### Basic Document

Create a new Quarto document in an existing project:

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

```{r, eval=FALSE}
froggeR::write_quarto(
  filename = "frog_standalone",
  custom_yaml = FALSE  # Basic Quarto template
)
```

### Document Types

`write_quarto()` supports two main workflows:

1. **Project Documents** (`custom_yaml = TRUE`)
    * Use project settings
    * Include custom styling
    * Maintain consistency

2. **Standalone Documents** (`custom_yaml = FALSE`)
    * Basic Quarto template
    * No external dependencies
    * Quick start for simple docs

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

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

```{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")
```

----

## 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 |
    | `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",
      custom_yaml = TRUE
    )
    
    froggeR::write_quarto(
      filename = "frogs",
      custom_yaml = TRUE
    )
    ```

3. **Project Structure**

    ```
    frogs/
    ├── frogs.qmd
    ├── data_prep.qmd
    ├── analysis.qmd
    ├── _variables.yml
    ├── custom.scss
    ├── dated_progress_notes.md
    └── 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 = "advanced_frogs")
```

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:

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