--- title: "Get Hopping with froggeR" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Get Hopping with froggeR} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## Introduction froggeR streamlines Quarto workflows by providing a robust, user-friendly framework for project setup and document creation. Leverage Quarto branding within your projects with froggeR's added functionality. This vignette demonstrates how froggeR can enhance your productivity while maintaining project consistency. ```r # Install from GitHub install.packages("kyleGrealis/froggeR") ``` ---- ## Core Features Project setup often involves repetitive tasks that can impede your analysis workflow. froggeR addresses this by providing: * Automated project initialization with [`quarto_project()`](https://azimuth-project.tech/froggeR/reference/quarto_project.html) * Reusable project configurations through [`settings()`](https://azimuth-project.tech/froggeR/reference/froggeR_settings.html) * Replicate Quarto project brand styling with [`write_brand()`](https://azimuth-project.tech/froggeR/reference/write_brand.html) and [`save_brand()`](https://azimuth-project.tech/froggeR/reference/save_brand.html) * Configurable document templates via [`write_quarto()`](https://azimuth-project.tech/froggeR/reference/write_quarto.html) * Consistent styling with [`write_scss()`](https://azimuth-project.tech/froggeR/reference/write_scss.html) * Enhanced version control setup * Easily add project documentation templates to any existing project, even those not initialized by froggeR. ---- ## SPOILER ALERT!! All of the components listed below are available when you begin your Quarto projects with: ```r froggeR::quarto_project() ``` Save time on building a project structure, formatting, branding, and trying to redo that super awesome YAML you did a few weeks back. Start with froggeR now and get yourself dialed in for all future projects! ---- ## Quick Start Guide Create a new Quarto project with a single command: ```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 command initializes a complete project structure with all necessary components: ### Project Components 1. **Quarto Document** * Pre-configured YAML header * Examples for adding brand logo, HTML in-document cross-references, and HTML links * Example for adding citations and references 2. **Style Sheet** * Modern design elements * Customizable components * Clear documentation 3. **Project Configuration** * `_quarto.yml` that is enhanced to simplify individual Quarto file YAML by centralizing document options. These can be changed on a per-document basis as well. * `_variables.yml` for consistent user metadata * `_brand.yml` for consistent project branding metadata * `.gitignore` for secure version control When you start your first Quarto project with froggeR, you're choosing fast & efficient templating over tedious replication of project documents. froggeR provides the ability to create project-level metadata (stored in `_quarto.yml`, `_variables.yml`, and `_brand.yml` files). This metadata allows users to reproduce a consistent structure & style across many Quarto projects. The `_quarto.yml` file serves as a central project structure file where you can set project-level Quarto document defaults such as toggling familiar rendering settings (i.e., `format` options, `code-tools`, `page-layout`). You can then reuse personal metadata by modifying the `_variables.yml` file. These values are then used by `_quarto.yml` where the `name` value in `_variables.yml` is pulled into the project YAML as `name: "{{< var name >}}"`. When you render the document, your actual name is displayed in the output. Adding your email, a personal or company URL, or your ORCID is just the same -- the `_variables.yml` file is composed of `key:value` pairs. You can also create & use variables if you follow the format. Now, this may seem like a lot of work for a basic Quarto project. You may be correct since the first project will take an extra few minutes of populating the `_variables.yml` file with your information and adjusting the `_quarto.yml` for project-level settings. However, once you `froggeR::save_variables()`, all of this work will be replicated immediately the *next* time you use froggeR to create your Quarto projects! I'm sure you can envision many more ways to use metadata to your advantage. This isn't a "froggeR-thing"... the great team working on [Quarto](https://quarto.org) is to thank! > **Note**: Deleting key:value pairs in the `_variables.yml` file requires you to also remove the corresponding fields in the `_quarto.yml`. It is recommended to comment out or leave blank the fields in `_variables.yml` that are not needed. See `vignette("customizing-quarto", package = "froggeR")` for more detailed configuration options. ---- ## Customization ### Document Settings > You may choose to setup your froggeR metadata before creating your first project. Manage your document settings with the interactive configuration tool (see `?froggeR::settings` for all options): ```r # Check, display, or update your settings >> froggeR::settings() froggeR settings options: 1: Check for config files 2: Display current settings 3: Show how to update settings 4: Show how to reuse settings across projects 5: More information about settings Selection: 1 ℹ Run froggeR::write_variables() to create project-level settings. ``` To create and open the `_variables.yml` file for immediate customization, run: ```r # Create project-level metadata froggeR::write_variables() ``` You will then see the file open with hints provided on how to fill in and use. Remember, it's better (and safer) to leave fields blank than to delete them... but you can remove the first two comment lines. ```r # You do not need to use quotes around values. # You may edit any value or leave it blank. name: email: orcid: url: #https://example.com affiliations: ``` Save this file then run `froggeR::save_variables()` to store this configuration file in your operating system's (OS) configuration file location (i.e., in Linux, this is `$HOME/.config/froggeR/config.yml`). This reinforce's froggeR's goal to increase your effeciency now and for future projects. These settings flow through your projects in this order: 1. `config.yml` stores your permanent settings (exact location depends on your OS) 2. froggeR reads these when creating new projects 3. Settings populate `_variables.yml` in your project 4. Quarto documents use these variables automatically