├── .Rbuildignore ├── .github ├── .gitignore └── workflows │ └── pkgdown.yaml ├── .gitignore ├── CRAN-SUBMISSION ├── DESCRIPTION ├── LICENSE ├── LICENSE.md ├── NAMESPACE ├── NEWS.md ├── R ├── froggeR-package.R ├── quarto_project.R ├── save_brand.R ├── save_variables.R ├── settings.R ├── utils.R ├── write_brand.R ├── write_ignore.R ├── write_notes.R ├── write_quarto.R ├── write_readme.R ├── write_scss.R └── write_variables.R ├── README.md ├── inst ├── WORDLIST └── gists │ ├── README.md │ ├── basic_quarto.qmd │ ├── brand.yml │ ├── config.yml │ ├── custom.scss │ ├── custom_quarto.qmd │ ├── gitignore │ ├── quarto.yml │ └── references.bib ├── man ├── figures │ ├── code_block_after.png │ ├── code_block_before.png │ ├── config-file.png │ ├── custom-scss-file.png │ ├── custom-yaml-init.png │ ├── custom-yaml-rendered.png │ ├── document_types.png │ ├── froggeR-init.png │ ├── froggeR_logo.svg │ ├── frogger_logo.png │ ├── key-value.png │ ├── link_color_after.png │ ├── link_color_before.png │ ├── logo.png │ ├── logo.svg │ ├── new-froggeR-session.png │ ├── project_init.png │ ├── project_structure.png │ ├── project_yaml.png │ ├── settings-options.png │ ├── variables-init.png │ ├── variables-yml.png │ ├── write-quarto-example.png │ └── yaml-comparison.png ├── quarto_project.Rd ├── save_brand.Rd ├── save_variables.Rd ├── settings.Rd ├── write_brand.Rd ├── write_ignore.Rd ├── write_notes.Rd ├── write_quarto.Rd ├── write_readme.Rd ├── write_scss.Rd └── write_variables.Rd ├── pkgdown ├── _pkgdown.yml └── favicon │ ├── apple-touch-icon.png │ ├── favicon-96x96.png │ ├── favicon.ico │ ├── favicon.svg │ ├── site.webmanifest │ ├── web-app-manifest-192x192.png │ └── web-app-manifest-512x512.png ├── tests ├── testthat.R └── testthat │ ├── test-quarto_project.R │ ├── test-write_ignore.R │ ├── test-write_notes.R │ ├── test-write_readme.R │ ├── test-write_scss.R │ └── test-write_variables.R └── vignettes ├── .gitignore ├── customizing-quarto.Rmd ├── hopping-into-quarto.Rmd └── quarto-workflow.Rmd /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | ^LICENSE\.md$ 4 | PROG_NOTES.md 5 | ^doc$ 6 | ^Meta$ 7 | ^docs$ 8 | ^_pkgdown\.yml$ 9 | ^pkgdown$ 10 | ^\.github$ 11 | .quarto$ 12 | ^cran-comments\.md$ 13 | ^CRAN-SUBMISSION$ 14 | ..Rcheck$ -------------------------------------------------------------------------------- /.github/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | -------------------------------------------------------------------------------- /.github/workflows/pkgdown.yaml: -------------------------------------------------------------------------------- 1 | # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples 2 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help 3 | on: 4 | push: 5 | branches: [main, master] 6 | pull_request: 7 | branches: [main, master] 8 | release: 9 | types: [published] 10 | workflow_dispatch: 11 | 12 | name: pkgdown.yaml 13 | 14 | permissions: read-all 15 | 16 | jobs: 17 | pkgdown: 18 | runs-on: ubuntu-latest 19 | # Only restrict concurrency for non-PR jobs 20 | concurrency: 21 | group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} 22 | env: 23 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 24 | permissions: 25 | contents: write 26 | steps: 27 | - uses: actions/checkout@v4 28 | 29 | - uses: r-lib/actions/setup-pandoc@v2 30 | 31 | - uses: r-lib/actions/setup-r@v2 32 | with: 33 | use-public-rspm: true 34 | 35 | - uses: r-lib/actions/setup-r-dependencies@v2 36 | with: 37 | extra-packages: any::pkgdown, local::. 38 | needs: website 39 | 40 | - name: Build site 41 | run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) 42 | shell: Rscript {0} 43 | 44 | - name: Deploy to GitHub pages 🚀 45 | if: github.event_name != 'pull_request' 46 | uses: JamesIves/github-pages-deploy-action@v4.5.0 47 | with: 48 | clean: false 49 | branch: gh-pages 50 | folder: docs 51 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Version 2024-05-18 2 | 3 | # History files 4 | .Rhistory 5 | .Rapp.history 6 | 7 | # Session Data files 8 | .RData 9 | *.RData 10 | .RDataTmp 11 | 12 | # User-specific files 13 | .Ruserdata 14 | 15 | # Example code in package build process 16 | *-Ex.R 17 | 18 | # Output files from R CMD build 19 | /*.tar.gz 20 | 21 | # Output files from R CMD check 22 | /*.Rcheck/ 23 | 24 | # RStudio files 25 | .Rproj.user 26 | .Rproj.user/ 27 | 28 | # produced vignettes 29 | vignettes/*.html 30 | vignettes/*.pdf 31 | 32 | # OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3 33 | .httr-oauth 34 | 35 | # knitr and R markdown default cache directories 36 | *_cache/ 37 | /cache/ 38 | 39 | # Temporary files created by R markdown 40 | *.utf8.md 41 | *.knit.md 42 | 43 | # R Environment Variables 44 | .Renviron 45 | 46 | # Mac 47 | .DS_Store 48 | .Thumbs.db 49 | Thumbs.db 50 | 51 | # Directories 52 | docs/ 53 | data/ 54 | development/ 55 | macros/ 56 | output/ 57 | sasdata/ 58 | libs/ 59 | 60 | # translation temp files 61 | po/*~ 62 | 63 | # RStudio Connect folder 64 | rsconnect/ 65 | 66 | ### R.Bookdown Stack ### 67 | # R package: bookdown caching files 68 | /*_files/ 69 | 70 | 71 | # Exclude .Rmd output 72 | *.html 73 | **/figure-html/ 74 | 75 | # Exclude Text 76 | *.txt 77 | *.Txt 78 | *.TXT 79 | 80 | # Exclude Excel 81 | *.xlsx 82 | *.xls 83 | 84 | # R data 85 | *.rds 86 | *.RDS 87 | *.Rds 88 | *.rda 89 | *.RDA 90 | *.Rda 91 | 92 | # csv data 93 | *.csv 94 | *.CSV 95 | *.Csv 96 | 97 | # sas data 98 | *.sas7bdat 99 | *.sas7bcat 100 | 101 | # SPSS data 102 | *.sav 103 | *.SAV 104 | *.Sav 105 | 106 | # SPSS output 107 | *.spv 108 | *.SPV 109 | *.Spv 110 | 111 | # STATA data 112 | *.dta 113 | *.DTA 114 | *.Dta 115 | 116 | # STATA log files 117 | *.log 118 | *.LOG 119 | *.Log 120 | *.smcl 121 | *.SMCL 122 | *.Smcl 123 | 124 | # data commonly used in Python 125 | *.json 126 | *.pkl 127 | *.h5 128 | *.msgpack 129 | *.parquet 130 | *.feather 131 | 132 | # VSC 133 | www/.vscode/ 134 | 135 | # Bookdown book 136 | _book/ 137 | _bookdown_files/ 138 | 139 | # Binary - Powerpoint and iThoughtsX 140 | *.ppt 141 | *.pptx 142 | *.itmz 143 | 144 | # R packages 145 | *.tar 146 | 147 | # Archives 148 | *.zip 149 | *.Zip 150 | *.ZIP 151 | 152 | # Quarto 153 | /.quarto/ 154 | /_site/ 155 | .quarto/ 156 | _site/ 157 | 158 | # project-level 159 | PROG_NOTES.md 160 | froggeR.Rproj 161 | inst/doc 162 | /doc/ 163 | /Meta/ 164 | docs 165 | cran-comments.md 166 | ^CRAN-SUBMISSION$ -------------------------------------------------------------------------------- /CRAN-SUBMISSION: -------------------------------------------------------------------------------- 1 | Version: 0.5.2 2 | Date: 2025-08-21 18:59:22 UTC 3 | SHA: 37024ba38959014366729eb84fccce2c2672c68f 4 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: froggeR 2 | Type: Package 3 | Title: Enhance 'Quarto' Project Workflows and Standards 4 | Version: 0.5.2 5 | Authors@R: 6 | person( 7 | "Kyle", 8 | "Grealis", 9 | email = "kyleGrealis@icloud.com", 10 | role = c("aut", "cre"), 11 | comment = c(ORCID = "0000-0002-9223-8854") 12 | ) 13 | Maintainer: Kyle Grealis 14 | Description: Streamlines 'Quarto' workflows by providing tools for consistent project setup and documentation. Enables portability through reusable metadata, automated project structure creation, and standardized templates. Features include enhanced project initialization, pre-formatted 'Quarto' documents, inclusion of 'Quarto' brand functionality, comprehensive data protection settings, custom styling, and structured documentation generation. Designed to improve efficiency and collaboration in R data science projects by reducing repetitive setup tasks while maintaining consistent formatting across multiple documents. 15 | License: MIT + file LICENSE 16 | Encoding: UTF-8 17 | RoxygenNote: 7.3.2 18 | Depends: 19 | R (>= 3.5.0) 20 | Imports: 21 | cli (>= 3.0.0), 22 | fs, 23 | glue (>= 1.6.0), 24 | here (>= 1.0.1), 25 | quarto (>= 1.3.0), 26 | rappdirs, 27 | readr (>= 2.0.0), 28 | rstudioapi, 29 | stringr (>= 1.5.0), 30 | usethis (>= 2.2.0), 31 | yaml 32 | Suggests: 33 | knitr, 34 | mockery, 35 | rmarkdown, 36 | testthat (>= 3.0.0), 37 | withr 38 | Config/build/copy-resources: 39 | inst/gists/basic_quarto.qmd 40 | inst/gists/custom_quarto.qmd 41 | inst/gists/README.md 42 | Config/testthat/edition: 3 43 | VignetteBuilder: knitr 44 | URL: https://www.kyleGrealis.com/froggeR/ 45 | BugReports: https://github.com/kyleGrealis/froggeR/issues 46 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | YEAR: 2024 2 | COPYRIGHT HOLDER: Kyle Grealis 3 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # MIT License 2 | 3 | Copyright (c) 2024 Kyle Grealis 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | export(quarto_project) 4 | export(save_brand) 5 | export(save_variables) 6 | export(settings) 7 | export(write_brand) 8 | export(write_ignore) 9 | export(write_notes) 10 | export(write_quarto) 11 | export(write_readme) 12 | export(write_scss) 13 | export(write_variables) 14 | importFrom(cli,col_blue) 15 | importFrom(cli,col_green) 16 | importFrom(fs,dir_copy) 17 | importFrom(glue,glue) 18 | importFrom(here,here) 19 | importFrom(quarto,quarto_create_project) 20 | importFrom(quarto,quarto_version) 21 | importFrom(rappdirs,user_config_dir) 22 | importFrom(readr,read_file) 23 | importFrom(readr,write_file) 24 | importFrom(rstudioapi,openProject) 25 | importFrom(stringr,str_replace) 26 | importFrom(stringr,str_to_lower) 27 | importFrom(usethis,ui_done) 28 | importFrom(usethis,ui_info) 29 | importFrom(usethis,ui_oops) 30 | importFrom(usethis,ui_todo) 31 | importFrom(usethis,ui_yeah) 32 | importFrom(utils,download.file) 33 | importFrom(utils,menu) 34 | importFrom(yaml,read_yaml) 35 | importFrom(yaml,write_yaml) 36 | -------------------------------------------------------------------------------- /NEWS.md: -------------------------------------------------------------------------------- 1 | # froggeR 0.5.1 2 | 3 | ## Enhancements 4 | * Minimal spelling corrections to `NEWS` and vignettes. *No functionality changes!* 5 | 6 | # froggeR 0.5.0 7 | 8 | ## BREAKING!! 9 | * `write_quarto()` argument `custom_yaml` has been replaced with `example`, defaulting to TRUE. The Quarto file templates have been reworked to use Quarto brand structure. This simplifies the YAML within the document, but may require changes to the project `_quarto.yml` and `_brand.yml` files. 10 | 11 | ## Enhancements 12 | * 2 new Quarto brand YAML functions have been added: `write_brand()` & `save_brand()`. These functions allow users to add project `_brand.yml` file and save the current `_brand.yml` to where your machine stores configuration files. There are added arguments to save & restore your brand logos (saved as `logos/` directory). 13 | * Modified SCSS template placeholders -- some of these are now easier to manage in the `_brand.yml` file. Added tweaks for ORCID logo issue when rendering with branding on Windows. 14 | * Revised Quarto template YAML -- this seems to be a constant work in progress. Weighing the value of including defaults versus a more minimalistic approach. 15 | * Removed creation of `.Rproj` file in `quarto_project()`. 16 | 17 | ## Bug Fixes 18 | * Corrected logic flow in `write_variables()` that caused unintentional stoppage. 19 | 20 | 21 | --- 22 | 23 | # froggeR 0.4.0 24 | 25 | ## Enhancements 26 | * NEW: `save_variables()` is a new function to store the current project-level `_variables.yml` to the system configuration file path. It offers to overwrite if the system config exists. 27 | * Simplified Quarto templates by removing unnecessary commenting throughout the YAML. 28 | * Added section for including multiple authors in Quarto YAML files. 29 | * Simplified README in favor of a more lightweight template. 30 | 31 | ## Bug Fixes 32 | * Corrected indentation error for `affiliations` in the standard, non-custom Quarto template. Created rendering error. 33 | 34 | ## Documentation 35 | * `save_variables()` documentation added to README 36 | 37 | ## Internal Changes 38 | * Fixed tests for `write_notes()` and `write_readme()` to reflect updated content. 39 | 40 | 41 | --- 42 | 43 | # froggeR 0.3.0 44 | 45 | ## Enhancements 46 | * The `settings()` function replaces `froggeR_settings` and provides a menu-driven interface. User's can now check, view, & get instructions to use Quarto metadata within and across projects. Learn how to apply user-specific metadata from the global config file, or store local project metadata for reuse on future froggeR Quarto projects. 47 | * The suite of `write_*` functions open the created files for immediate viewing & editing (in interactive sessions). 48 | * Revised console feedback so users are always informed about how froggeR is helping streamline your project. 49 | 50 | ## Bug Fixes 51 | * *None* 52 | 53 | ## Documentation 54 | * Fixed roxygen documentation for `@examples` by using `tempdir()` when executing functions. 55 | * Used `@inheretParams` across supplemental functions (README, notes, ignore, SCSS, variables). 56 | 57 | ## Internal Changes 58 | * Removed ability to change metadata from the console. Instructions are now provided and, for `write_variables()`, the config file is opened in the interactive session. 59 | * Separated `write_readme`; now includes `write_notes` for a project-level progress notes template. 60 | * If any document to be created from the `write_*` functions exists in the project, froggeR will now stop and provide a useful message *instead* of offering to overwrite from the console. This reduces annoying feedback & interaction and encourages the user to make deliberate decisions. 61 | 62 | 63 | --- 64 | 65 | # froggeR 0.2.2 66 | 67 | ## Enhancements 68 | * **`quarto_project()`**: 69 | - Streamlined integration with auxiliary functions for creating project-level files. 70 | - Improved error handling and user feedback when creating Quarto projects. 71 | - Ensured proper connection to `write_variables()` for managing `_variables.yml`. 72 | 73 | * **`write_quarto()`**: 74 | - Enhanced functionality to automatically call `write_variables()` for `_variables.yml` creation. 75 | - Added clearer messaging for users when froggeR settings are missing, guiding them to set up metadata. 76 | 77 | * **`write_variables()`**: 78 | - Introduced as a new function to create and manage `_variables.yml` files in a modular way. 79 | - Handles automatic population of YAML metadata using froggeR settings. 80 | 81 | * **Improved User Feedback**: 82 | - Refined messaging across functions for consistency and clarity, including updated `ui_done` and `ui_info` outputs. 83 | 84 | ## Bug Fixes 85 | * Resolved CRAN `check()` errors related to undefined global variables in examples. 86 | * Fixed issues where `_variables.yml` creation would fail under specific directory conditions. 87 | 88 | ## Documentation 89 | * Enhanced roxygen documentation for `write_quarto()`, `quarto_project()`, and `write_variables()` with detailed examples and explanations. 90 | * Updated vignettes to demonstrate the modular design and improved workflows. 91 | 92 | ## Internal Changes 93 | * Consolidated helper functions into `helpers.R` for better maintainability and organization. 94 | * Improved modularity of settings and file management functions to align with best practices. 95 | 96 | 🎉 With version 0.2.2, froggeR introduces more robust Quarto project management, making metadata handling and customization easier and more intuitive for users. 97 | 98 | 99 | --- 100 | 101 | # froggeR 0.2.1 102 | 103 | ## Enhancements 104 | * Improved `write_scss()` function for more streamlined YAML updates in Quarto documents. 105 | * Enhanced user feedback in `froggeR_settings()` function, providing clearer output of current settings. 106 | * Refined error handling and user guidance in various functions for a smoother user experience. 107 | * Updated vignettes with more comprehensive examples and clearer explanations of froggeR workflows. 108 | 109 | ## Documentation 110 | * Expanded and clarified documentation for key functions. 111 | * Added more detailed examples in function documentation to illustrate various use cases. 112 | * Updated README with additional information on package usage and benefits. 113 | 114 | # froggeR 0.2.0 115 | * Renamed `default` parameter to `custom_yaml` in `quarto_project()` and `write_quarto()` for clarity. 116 | * Refactored `froggeR_settings()` to use YAML for configuration storage. 117 | * Changed how settings are stored and retrieved. Settings are now stored in `~/.config/froggeR/config.yml`. 118 | * Improved user interaction in `froggeR_settings()` function. 119 | * Modified `quarto_project()` and `write_quarto()` to use the new YAML-based settings. 120 | * Added `.check_settings()` function to provide user feedback on incomplete settings. 121 | * Updated `.update_variables_yml()` function to handle both creation and updating of `_variables.yml`. 122 | * Improved error handling and user feedback in various functions. 123 | * Removed `load_data()` function and related utilities. 124 | * Updated documentation and examples to reflect new functionality and improve clarity. 125 | * Revised README for better explanation of package workflow and features. 126 | * Updated pkgdown site structure to reflect current package organization. 127 | 128 | # froggeR 0.1.0 129 | 130 | ## Major Features 131 | * Implemented enhanced Quarto project creation with `quarto_project()` 132 | - Automated project structure setup 133 | - Custom YAML integration 134 | - Built-in .gitignore configuration 135 | - Project documentation templates 136 | 137 | * Added interactive YAML configuration via `froggeR_settings()` 138 | - Author information management 139 | - Contact details setup 140 | - Project metadata configuration 141 | - TOC preferences 142 | 143 | * Created document generation tools 144 | - `write_quarto()` for consistent document creation 145 | - `write_readme()` for structured project documentation 146 | - `write_ignore()` for enhanced Git security 147 | - `write_scss()` for custom styling templates 148 | 149 | ## Documentation 150 | * Added comprehensive function documentation 151 | * Included detailed examples for all main functions 152 | * Created structured README with clear usage guidelines 153 | * Added function reference table 154 | 155 | ## Project Structure 156 | * Implemented consistent project organization 157 | * Added template system for Quarto documents 158 | * Created reusable YAML configuration system 159 | * Added custom SCSS styling templates 160 | 161 | ## Security 162 | * Enhanced data protection through comprehensive .gitignore settings 163 | * Added safeguards for sensitive data files 164 | * Implemented security best practices for R projects -------------------------------------------------------------------------------- /R/froggeR-package.R: -------------------------------------------------------------------------------- 1 | #' @keywords internal 2 | #' @noRd 3 | "_PACKAGE" 4 | 5 | ## usethis namespace: start 6 | #' @importFrom cli col_blue col_green 7 | #' @importFrom fs dir_copy 8 | #' @importFrom glue glue 9 | #' @importFrom here here 10 | #' @importFrom quarto quarto_create_project quarto_version 11 | #' @importFrom rappdirs user_config_dir 12 | #' @importFrom readr read_file write_file 13 | #' @importFrom rstudioapi openProject 14 | #' @importFrom stringr str_replace str_to_lower 15 | #' @importFrom usethis ui_done ui_info ui_oops ui_todo ui_yeah 16 | #' @importFrom utils download.file menu 17 | #' @importFrom yaml read_yaml write_yaml 18 | ## usethis namespace: end 19 | NULL -------------------------------------------------------------------------------- /R/quarto_project.R: -------------------------------------------------------------------------------- 1 | #' Create a Custom 'Quarto' Project 2 | #' 3 | #' This function creates a new 'Quarto' project directory with additional froggeR 4 | #' features. It first calls \code{quarto::quarto_create_project()} to set up the 5 | #' basic structure, then enhances it with froggeR-specific files and settings. 6 | #' 7 | #' @param name Character string. The name of the 'Quarto' project directory and 8 | #' initial \code{.qmd} file. 9 | #' @param path Character string. Path to the project directory. 10 | #' @param example Logical. If TRUE (default), creates a Quarto document with a default to 11 | #' position the brand logo and examples of within-document cross-referencing, links, 12 | #' and references. 13 | #' 14 | #' @return Invisibly returns the path to the created project directory. 15 | #' 16 | #' @details 17 | #' This function creates a 'Quarto' project with the following enhancements: 18 | #' \itemize{ 19 | #' \item \code{_brand.yml}: Stores Quarto project branding 20 | #' \item \code{logos}: Quarto project branding logos directory 21 | #' \item \code{_variables.yml}: Stores reusable YAML variables 22 | #' \item \code{.gitignore}: Enhanced settings for R projects 23 | #' \item \code{README.md}: Template README file 24 | #' \item \code{dated_progress_notes.md}: For project progress tracking 25 | #' \item \code{custom.scss}: Custom 'Quarto' styling 26 | #' } 27 | #' If froggeR settings don't exist, it will prompt to create them. 28 | #' 29 | #' @seealso \code{\link{write_quarto}}, \code{\link{settings}} 30 | #' 31 | #' @examples 32 | #' if (interactive() && quarto::quarto_version() >= "1.6") { 33 | #' 34 | #' # Create the Quarto project with custom YAML & associated files 35 | #' quarto_project("frogs", path = tempdir(), example = TRUE) 36 | #' 37 | #' # Confirms files were created (optional, for user confirmation) 38 | #' file.exists(file.path(tempdir(), "frogs.qmd")) # Quarto doc 39 | #' file.exists(file.path(tempdir(), "_quarto.yml")) # project YAML file 40 | #' 41 | #' # Create a new Quarto project with standard Quarto (no examples) 42 | #' # quarto_project('frogs_standard', path = tempdir(), example = FALSE) 43 | #' 44 | #' } 45 | #' 46 | #' @export 47 | quarto_project <- function(name, path = here::here(), example = TRUE) { 48 | 49 | quarto_version <- quarto::quarto_version() 50 | if (quarto_version < "1.6") stop("You need Quarto version 1.6 or greater to use froggeR Quarto projects. See http://quarto.org/docs/download to upgrade.") 51 | 52 | # Validate path 53 | if (is.null(path) || is.na(path) || !dir.exists(path)) { 54 | stop("Invalid `path`. Please enter a valid project directory.") 55 | } 56 | 57 | # Validate name 58 | if (!grepl('^[a-zA-Z0-9_-]+$', name)) { 59 | stop( 60 | 'Invalid project name. Use only letters, numbers, hyphens, and underscores.', 61 | '\nExample: "my-project" or "frog_analysis"' 62 | ) 63 | } 64 | 65 | if (!is.logical(example)) { 66 | stop('Parameter `example` must be TRUE or FALSE') 67 | } 68 | 69 | # Normalize the base directory path 70 | path <- normalizePath(path, mustWork = TRUE) 71 | 72 | # Create the full project path 73 | project_dir <- file.path(path, name) 74 | 75 | # Check if directory exists 76 | if (dir.exists(project_dir)) { 77 | stop(sprintf('Directory named "%s" exists in %s.', name, path)) 78 | } 79 | 80 | # Create the Quarto project 81 | frog_prompt <- if (interactive()) FALSE else TRUE 82 | quarto::quarto_create_project(name, dir = path, quiet = TRUE, no_prompt = frog_prompt) 83 | ui_done(sprintf('Created Quarto project directory: %s', name)) 84 | 85 | # Remove default files created by Quarto only if they exist 86 | default_quarto_yml <- file.path(project_dir, '_quarto.yml') 87 | default_qmd <- file.path(project_dir, paste0(name, '.qmd')) 88 | default_ignore <- file.path(project_dir, '.gitignore') 89 | if (file.exists(default_qmd)) file.remove(default_qmd) 90 | if (file.exists(default_quarto_yml)) file.remove(default_quarto_yml) 91 | if (file.exists(default_ignore)) file.remove(default_ignore) 92 | 93 | ######################################################################## 94 | ## .initialize_proj = TRUE stops the file from opening upon creation ## 95 | ## since all of the new files are written to a new project location. ## 96 | ## If they were to be opened immediately, they would NOT open in the ## 97 | ## chosen project directory ## 98 | ######################################################################## 99 | 100 | # Add _quarto.yml & modify 101 | template_path <- system.file('gists/quarto.yml', package = 'froggeR') 102 | the_quarto_file <- file.path(project_dir, "_quarto.yml") 103 | file.copy(from = template_path, to = the_quarto_file, overwrite = FALSE) 104 | # Update the title with the project name 105 | quarto_content <- readr::read_file(the_quarto_file) 106 | updated_content <- stringr::str_replace( 107 | quarto_content, 108 | " title: \"\"", 109 | sprintf(" title: \"%s\"", name) 110 | ) 111 | readr::write_file(updated_content, the_quarto_file) 112 | ui_done("Created _quarto.yml") 113 | 114 | # Create project files 115 | froggeR::write_variables(path = project_dir, .initialize_proj = TRUE) 116 | froggeR::write_brand(path = project_dir, .initialize_proj = TRUE) 117 | froggeR::write_scss(path = project_dir, .initialize_proj = TRUE) 118 | froggeR::write_ignore(path = project_dir, .initialize_proj = TRUE) 119 | froggeR::write_readme(path = project_dir, .initialize_proj = TRUE) 120 | froggeR::write_notes(path = project_dir, .initialize_proj = TRUE) 121 | 122 | # Create Quarto document 123 | froggeR::write_quarto( 124 | filename = name, 125 | path = project_dir, 126 | example = example, 127 | .initialize_proj = TRUE 128 | ) 129 | 130 | # Add references.bib 131 | ref_template_path <- system.file('gists/references.bib', package = 'froggeR') 132 | the_ref_file <- file.path(project_dir, "references.bib") 133 | file.copy(from = ref_template_path, to = the_ref_file, overwrite = FALSE) 134 | ui_done("Created references.bib") 135 | 136 | # Start & open the project 137 | ui_done( 138 | sprintf( 139 | '%s project setup complete. Opening in new session...', col_green('froggeR') 140 | ) 141 | ) 142 | 143 | # Open project in new window & session: 144 | if (interactive()) rstudioapi::openProject(path = project_dir, newSession = TRUE) 145 | 146 | # Return the project directory path invisibly 147 | invisible(project_dir) 148 | } 149 | -------------------------------------------------------------------------------- /R/save_brand.R: -------------------------------------------------------------------------------- 1 | #' Save brand YAML for 'Quarto' Projects 2 | #' 3 | #' This function saves the current `_brand.yml` file from an existing froggeR 4 | #' Quarto project. This provides a safety catch to prevent unintended overwrite if the 5 | #' system-level configuration file exists. 6 | #' 7 | #' @param save_logos Logical. Save brand logos from `logos` directory. Default is `TRUE`. 8 | #' 9 | #' @return Invisibly returns `NULL` after creating system-level configuration file. 10 | #' @details 11 | #' The function will attempt to create a system-level configuration file from the current 12 | #' froggeR Quarto project. If the system-level configuration file already exists, the 13 | #' user will be prompted prior to overwrite. 14 | #' 15 | #' @examples 16 | #' 17 | #' # Write the _brand.yml file 18 | #' if (interactive()) save_brand() 19 | #' 20 | #' @export 21 | save_brand <- function(save_logos = TRUE) { 22 | # Normalize the path for consistency 23 | path <- normalizePath(here::here(), mustWork = TRUE) 24 | 25 | # Set up full origin file path 26 | the_brand_file <- file.path(path, '_brand.yml') 27 | 28 | # Check for project-level _brand.yml 29 | if (!file.exists(the_brand_file)) { 30 | ui_oops( 31 | sprintf( 32 | 'No current _brand.yml file exists in this project. Run %s to create it.', 33 | col_green('froggeR::write_brand()') 34 | ) 35 | ) 36 | return(invisible(NULL)) 37 | } 38 | 39 | # Global froggeR settings 40 | config_path <- rappdirs::user_config_dir("froggeR") 41 | brand_file <- file.path(config_path, "_brand.yml") 42 | # Does it exist? 43 | system_settings <- file.exists(brand_file) 44 | # Overwrite_prompt 45 | overwrite_prompt <- sprintf( 46 | "A system-level %s configuration was found. Overwrite??", 47 | col_green("froggeR") 48 | ) 49 | 50 | # Save the config file or prompt the user to overwrite 51 | if (system_settings) { 52 | if (ui_yeah(overwrite_prompt)) { 53 | file.copy(from = the_brand_file, to = brand_file, overwrite = TRUE) 54 | ui_info(sprintf('Copying project %s settings...', col_green('froggeR'))) 55 | ui_done(sprintf("Saved _brand.yml to system configuration: \n%s", brand_file)) 56 | } else { 57 | ui_oops('No changes were made.') 58 | } 59 | } else { 60 | file.copy(from = the_brand_file, to = brand_file, overwrite = FALSE) 61 | ui_info(sprintf('Copying project %s settings...', col_green('froggeR'))) 62 | ui_done(sprintf("Saved _brand.yml to system configuration: \n%s", brand_file)) 63 | } 64 | 65 | # Quarto brand logos directory 66 | # Does local directory exist? 67 | logos_dir <- dir.exists("logos") 68 | # No logos directory prompt 69 | no_local_logos <- "No project-level 'logos' directory was found. Skipping..." 70 | # Does the froggeR logos directory exist? 71 | frogger_logos <- dir.exists(file.path(config_path, "logos")) 72 | # Overwrite config logos prompt 73 | config_logos_overwrite <- sprintf( 74 | "A system-level %s configuration was found. Overwrite??", 75 | col_green("froggeR logos") 76 | ) 77 | 78 | # Save the local logos directory to froggeR configs 79 | if (save_logos) { 80 | # No logos directory 81 | if (!logos_dir) { 82 | ui_oops(no_local_logos) 83 | } else if (frogger_logos) { 84 | # Local & config exists -- ask to overwrite 85 | if (ui_yeah(config_logos_overwrite)) { 86 | fs::dir_copy("logos", file.path(config_path, "logos"), overwrite = TRUE) 87 | ui_done("Saved logos directory to system configuration") 88 | } else { 89 | ui_oops("Logos directory not copied.") 90 | } 91 | } else { 92 | fs::dir_copy("logos", file.path(config_path, "logos"), overwrite = TRUE) 93 | ui_done("Saved logos directory to system configuration") 94 | } 95 | } 96 | 97 | return(invisible(NULL)) 98 | } 99 | -------------------------------------------------------------------------------- /R/save_variables.R: -------------------------------------------------------------------------------- 1 | #' Save variables YAML for 'Quarto' Projects 2 | #' 3 | #' This function saves the current `_variables.yml` file from an existing froggeR 4 | #' Quarto project. This provides a safety catch to prevent unintended overwrite if the 5 | #' system-level configuration file exists. 6 | #' 7 | #' @return Invisibly returns `NULL` after creating system-level configuration file. 8 | #' @details 9 | #' The function will attempt to create a system-level configuration file from the current 10 | #' froggeR Quarto project. If the system-level configuration file already exists, the 11 | #' user will be prompted prior to overwrite. 12 | #' 13 | #' @examples 14 | #' 15 | #' # Write the _variables.yml file 16 | #' if (interactive()) save_variables() 17 | #' 18 | #' @export 19 | save_variables <- function() { 20 | # Normalize the path for consistency 21 | path <- normalizePath(here::here(), mustWork = TRUE) 22 | 23 | # Set up full origin file path 24 | the_variables_file <- file.path(path, '_variables.yml') 25 | 26 | # Check for project-level _variables.yml 27 | if (!file.exists(the_variables_file)) { 28 | ui_oops( 29 | sprintf( 30 | 'No current _variables.yml file exists in this project. Run %s to create it.', 31 | col_green('froggeR::write_variables()') 32 | ) 33 | ) 34 | return(invisible(NULL)) 35 | } 36 | 37 | # Global froggeR settings 38 | config_path <- rappdirs::user_config_dir("froggeR") 39 | config_file <- file.path(config_path, "config.yml") 40 | # Does it exist? 41 | system_settings <- file.exists(config_file) 42 | # Overwrite_prompt 43 | overwrite_prompt <- sprintf( 44 | "A system-level %s configuration was found. Overwrite??", 45 | col_green("froggeR") 46 | ) 47 | 48 | # Save the config file or prompt the user to overwrite 49 | if (system_settings) { 50 | if (ui_yeah(overwrite_prompt)) { 51 | file.copy(from = the_variables_file, to = config_file, overwrite = TRUE) 52 | } else { 53 | ui_oops('No changes were made.') 54 | } 55 | } else { 56 | file.copy(from = the_variables_file, to = config_file, overwrite = FALSE) 57 | } 58 | 59 | ui_info(sprintf('Copying project %s settings...', col_green('froggeR'))) 60 | ui_done(sprintf( 61 | "Saved _variables.yml to system configuration: \n%s", 62 | config_file 63 | )) 64 | 65 | return(invisible(NULL)) 66 | } 67 | -------------------------------------------------------------------------------- /R/settings.R: -------------------------------------------------------------------------------- 1 | #' Manage 'froggeR' Settings 2 | #' 3 | #' This function provides useful instructions and information regarding `froggeR` 4 | #' settings. 5 | #' 6 | #' @details This function can only run in an interactive environment. Choose to: 7 | #' - Check for the existence of project- and global-level configuration files 8 | #' - Display current project-level settings 9 | #' - Feedback for updating settings 10 | #' - Instructions how to reuse settings across multiple `froggeR` Quarto projects. 11 | #' 12 | #' @return No return value; called for side-effects. 13 | #' 14 | #' @examples 15 | #' # Only run in an interactive environment 16 | #' if (interactive()) froggeR::settings() 17 | #' 18 | #' @export 19 | settings <- function() { 20 | 21 | if (!interactive()) { stop('Must be run in interactive session. Exiting...')} 22 | 23 | frog <- utils::menu( 24 | choices = c( 25 | 'Check for config files', 26 | 'Display current settings', 27 | 'Show how to update settings', 28 | 'Show how to reuse settings across projects', 29 | 'More information about settings' 30 | ), 31 | title = sprintf('\n%s settings options:', col_green('froggeR')) 32 | ) 33 | 34 | # Project-level settings 35 | settings_file <- file.path(here::here(), '_variables.yml') 36 | # Global froggeR settings 37 | config_path <- rappdirs::user_config_dir("froggeR") 38 | config_file <- file.path(config_path, "config.yml") 39 | 40 | # Do they exist? 41 | project_settings <- file.exists(settings_file) 42 | froggeR_settings <- file.exists(config_file) 43 | 44 | switch( 45 | frog, 46 | c(.check(config_file, project_settings, froggeR_settings), .how_to()), 47 | .display(config_file, project_settings, froggeR_settings), 48 | .update(settings_file), 49 | .reuse(config_file, project_settings, froggeR_settings), 50 | .more_info() 51 | ) 52 | 53 | return(invisible(NULL)) 54 | } 55 | -------------------------------------------------------------------------------- /R/utils.R: -------------------------------------------------------------------------------- 1 | # Helpers: --------------------------------------------------- 2 | 3 | #' Console output function 4 | #' 5 | #' Internal helper to provide info about project-level settings 6 | #' @noRd 7 | .yes_settings <- function() { 8 | ui_done('Project-level settings file (`_variables.yml`) found.') 9 | } 10 | 11 | #' Console output function 12 | #' 13 | #' Internal helper to provide info about project-level settings 14 | #' @noRd 15 | .no_settings <- function() { 16 | ui_oops('No project-level settings file (`_variables.yml`) found.') 17 | } 18 | 19 | #' Console output function 20 | #' 21 | #' Internal helper to provide info about project-level settings 22 | #' @noRd 23 | .global_settings <- function(config_file) { 24 | ui_done(sprintf('Global %s settings found at: %s', col_green('froggeR'), config_file)) 25 | } 26 | 27 | #' Console output function 28 | #' 29 | #' Internal helper to provide info about creating project-level settings 30 | #' @noRd 31 | .how_to <- function() { 32 | ui_info( 33 | sprintf( 34 | 'Run %s to create project-level settings.', 35 | col_green('froggeR::write_variables()') 36 | ) 37 | ) 38 | } 39 | 40 | 41 | #' Check for existence of configuration files 42 | #' 43 | #' Internal helper to verify presence of project and global settings files. 44 | #' @param config_file Path to global config file 45 | #' @param project_settings Logical indicating if project settings exist 46 | #' @param froggeR_settings Logical indicating if global settings exist 47 | #' @noRd 48 | .check <- function(config_file, project_settings, froggeR_settings) { 49 | 50 | if (project_settings && froggeR_settings) { 51 | # Has both project and froggeR settings 52 | .yes_settings() 53 | .global_settings(config_file) 54 | ui_done('You are currently using project- and global-level settings.') 55 | 56 | } else if (project_settings && !froggeR_settings) { 57 | # Has only project settings 58 | .yes_settings() 59 | ui_oops(sprintf('No global %s config file found', col_green('froggeR'))) 60 | 61 | } else if (froggeR_settings && !project_settings) { 62 | # Has only froggeR settings 63 | .no_settings() 64 | ui_info(sprintf( 65 | 'However, a %s config file was found at: %s', col_green('froggeR'), config_file 66 | )) 67 | 68 | } else { 69 | ui_oops('No project-level or global settings file found.') 70 | } 71 | } 72 | 73 | #' Check for ability to display project-level configuration file 74 | #' 75 | #' Internal helper to display contents of project settings file. 76 | #' @param config_file Path to global config file 77 | #' @param project_settings Logical indicating if project settings exist 78 | #' @param froggeR_settings Logical indicating if global settings exist 79 | #' @noRd 80 | .display <- function(config_file, project_settings, froggeR_settings) { 81 | if (project_settings) { 82 | message('\nYour `_variables.yml` contents:\n') 83 | cat(readLines(here::here('_variables.yml')), sep = '\n') 84 | } else if (froggeR_settings) { 85 | .no_settings() 86 | ui_info(sprintf( 87 | 'However, a %s config file was found at: %s', col_green('froggeR'), config_file 88 | )) 89 | cat(readLines(config_file), sep = '\n') 90 | } else { 91 | ui_oops('No project-level or global settings file found.') 92 | .how_to() 93 | } 94 | } 95 | 96 | #' Check for ability to update project-level configuration file 97 | #' 98 | #' Internal helper to update project settings file. 99 | #' @param settings_file Path of project settings file (`_variables.yml`) 100 | #' @noRd 101 | .update <- function(settings_file) { 102 | if (file.exists(settings_file)) { 103 | .yes_settings() 104 | ui_info('Open the `_variables.yml` file to update project-level settings.') 105 | } else { 106 | .no_settings() 107 | .how_to() 108 | } 109 | } 110 | 111 | #' Check for ability to reuse configuration files 112 | #' 113 | #' Internal helper to verify reusability of project and global settings files. 114 | #' @param config_file Path to global config file 115 | #' @param project_settings Logical indicating if project settings exist 116 | #' @param froggeR_settings Logical indicating if global settings exist 117 | #' @noRd 118 | .reuse <- function(config_file, project_settings, froggeR_settings) { 119 | 120 | if (project_settings && froggeR_settings) { 121 | # Has both project and froggeR settings 122 | .yes_settings() 123 | .global_settings(config_file) 124 | ui_info('You are currently using project- and global-level settings.') 125 | 126 | } else if (project_settings && !froggeR_settings) { 127 | # Has only project settings 128 | .yes_settings() 129 | ui_info( 130 | sprintf( 131 | 'To reuse your current project-level settings (`_variables.yml`) for your next %s Quarto project, save the settings file to a special configurations folder. Run %s', 132 | col_green('froggeR'), 133 | col_green('froggeR::save_variables()') 134 | ) 135 | ) 136 | message( 137 | sprintf( 138 | '\n\nYour personalized configurations will automatically be used during your next %s Quarto project.', 139 | col_green('froggeR') 140 | ) 141 | ) 142 | 143 | } else if (froggeR_settings && !project_settings) { 144 | # Has only froggeR settings 145 | ui_info( 146 | sprintf( 147 | 'To reuse your global %s YAML settings (name, email, etc.) in your current project path (%s), run %s', 148 | col_green('froggeR'), here::here(), col_green('froggeR::save_variables()') 149 | ) 150 | ) 151 | 152 | } else { 153 | # Neither settings found 154 | ui_info( 155 | sprintf( 156 | 'Run `froggeR::write_variables() to create project-level settings.\nTo reuse them in your next %s Quarto project, run %s', 157 | col_green('froggeR'), 158 | col_green('froggeR::save_variables()') 159 | ) 160 | ) 161 | } 162 | } 163 | 164 | #' Console output function 165 | #' 166 | #' Internal helper to provide info about using `froggeR` settings 167 | #' @noRd 168 | .more_info <- function() { 169 | ui_info('Run `vignette(package = "froggeR")` to find out how to effectively use settings across multiple projects.') 170 | } 171 | 172 | #' Write .Rproj File 173 | #' 174 | #' Helper function to create or overwrite an RStudio project file (.Rproj). 175 | #' Ensures consistent settings across froggeR projects. 176 | #' 177 | #' @inheritParams write_ignore 178 | #' @param name Character string. Name of the .Rproj file. 179 | #' @return Invisibly returns NULL after creating the .Rproj file. 180 | #' @noRd 181 | .write_rproj <- function(name = here::here(), path) { 182 | # Validate path 183 | if (is.null(path) || is.na(path) || !dir.exists(path)) { 184 | stop("Invalid `path`. Please enter a valid project directory.") 185 | } 186 | 187 | # Normalize the path for consistency 188 | path <- normalizePath(path, mustWork = TRUE) 189 | 190 | # Define the target file path 191 | the_rproj_file <- file.path(path, paste0(name, ".Rproj")) 192 | 193 | # Check for existing .Rproj 194 | if (file.exists(the_rproj_file)) { 195 | stop('.Rproj found in project directory!') 196 | } 197 | 198 | # Define .Rproj content 199 | content <- "Version: 1.0\nRestoreWorkspace: Default\nSaveWorkspace: Default\nAlwaysSaveHistory: Default\nEnableCodeIndexing: Yes\nUseSpacesForTab: Yes\nNumSpacesForTab: 2\nEncoding: UTF-8\nRnwWeave: Sweave\nLaTeX: pdfLaTeX\nAutoAppendNewline: Yes\nStripTrailingWhitespace: Yes\n" 200 | 201 | # Write .Rproj file 202 | writeLines(content, the_rproj_file) 203 | ui_done(paste0("Created ", name, ".Rproj")) 204 | 205 | return(invisible(NULL)) 206 | } 207 | 208 | #' Helper for creating custom.scss & _quarto.yml 209 | #' 210 | #' @inheritParams write_ignore 211 | #' @return SCSS file, Quarto project YAML file, or both 212 | #' @noRd 213 | .ensure_auxiliary_files <- function(path, .initialize_proj) { 214 | # Validate the path 215 | if (!dir.exists(path)) { 216 | stop("Invalid path. The specified directory does not exist.") 217 | } 218 | 219 | # Define paths for auxiliary files 220 | quarto_yml_path <- file.path(path, '_quarto.yml') 221 | scss_path <- file.path(path, 'custom.scss') 222 | 223 | # Handle _quarto.yml 224 | if (!file.exists(quarto_yml_path)) { 225 | writeLines("project:\n title: \"Quarto Project\"", quarto_yml_path) 226 | ui_done("Created _quarto.yml") 227 | } 228 | 229 | # Handle custom.scss 230 | if (!file.exists(scss_path)) { 231 | write_scss(path = path, .initialize_proj = .initialize_proj) 232 | } 233 | } 234 | -------------------------------------------------------------------------------- /R/write_brand.R: -------------------------------------------------------------------------------- 1 | #' Write Brand YAML for 'Quarto' Projects 2 | #' 3 | #' This function creates or updates the `_brand.yml` file in a Quarto project 4 | #' directory if they exist in the config path. 5 | #' 6 | #' @inheritParams write_ignore 7 | #' @param restore_logos Logical. Restore logo content from system configuration. 8 | #' Default is `TRUE`. 9 | #' 10 | #' @return Invisibly returns `NULL` after creating or updating the `_brand.yml` file. 11 | #' @details 12 | #' The function will attempt to use the current froggeR settings from the config path. If 13 | #' no global configurations exist, a template `_brand.yml` will be created. 14 | #' 15 | #' @examples 16 | #' 17 | #' # Write the _brand.yml file 18 | #' if (interactive()) { 19 | #' temp_dir <- tempdir() 20 | #' write_brand(temp_dir) 21 | #' } 22 | #' 23 | #' @export 24 | write_brand <- function( 25 | path = here::here(), restore_logos = TRUE, .initialize_proj = FALSE 26 | ) { 27 | # Validate path 28 | if (is.null(path) || is.na(path) || !dir.exists(path)) { 29 | stop("Invalid `path`. Please enter a valid project directory.") 30 | } 31 | 32 | # Normalize the path for consistency 33 | path <- normalizePath(path, mustWork = TRUE) 34 | 35 | # Set up full destination file path 36 | the_branding_file <- file.path(path, '_brand.yml') 37 | 38 | # Handle _brand.yml creation 39 | if (file.exists(the_branding_file)) { 40 | stop('_brand.yml already exists in this project.') 41 | } 42 | 43 | # Global froggeR settings 44 | config_path <- rappdirs::user_config_dir("froggeR") 45 | brand_file <- file.path(config_path, "_brand.yml") 46 | # Does it exist? 47 | froggeR_brand <- file.exists(brand_file) 48 | 49 | # Write the config file based on template: if there's a .config/froggeR file, 50 | # use that or else use the template found here in the package 51 | template_path <- if (froggeR_brand) { 52 | # Display message if using the .config/froggeR/_brand.yml file 53 | ui_info(sprintf('Copying existing %s brand settings...', col_green('froggeR'))) 54 | brand_file 55 | } else { 56 | system.file('gists/brand.yml', package = 'froggeR') 57 | } 58 | 59 | if (template_path == "") { 60 | stop("Could not find config template in package installation") 61 | } 62 | 63 | file.copy(from = template_path, to = the_branding_file, overwrite = FALSE) 64 | ui_done("Created _brand.yml") 65 | 66 | if (!.initialize_proj) usethis::edit_file(the_branding_file) 67 | 68 | # Restore from logos directory or create it 69 | # Global froggeR logos 70 | frogger_logos <- file.path(config_path, "logos") 71 | # Does it exist? 72 | logos_dir <- dir.exists(frogger_logos) 73 | 74 | # Handle logos creation 75 | if (restore_logos) { 76 | # Logos desination path 77 | logos_dest <- file.path(path, "logos") 78 | 79 | if (dir.exists("logos")) { 80 | ui_oops("Logos directory already exists in this project. Skipping...") 81 | } else if(!logos_dir) { 82 | ui_info("No config level 'logos' directory was found. Skipping...") 83 | } else { 84 | fs::dir_copy(frogger_logos, logos_dest) 85 | ui_done(sprintf('Copying existing %s logos.', col_green('froggeR'))) 86 | } 87 | } 88 | 89 | return(invisible(NULL)) 90 | } 91 | -------------------------------------------------------------------------------- /R/write_ignore.R: -------------------------------------------------------------------------------- 1 | #' Create an enhanced \code{.gitignore} file 2 | #' 3 | #' This function creates a \code{.gitignore} file with enhanced security 4 | #' measures designed to help prevent accidental data leaks. The template includes 5 | #' comprehensive rules for common data file types and sensitive information. 6 | #' 7 | #' @param path Character string. Path to the project directory. 8 | #' @param .initialize_proj Logical. TRUE only if starting a 9 | #' \code{froggeR::quarto_project()}. 10 | #' 11 | #' @return A \code{.gitignore} file with enhanced security rules. The file includes:\cr 12 | #' * R data files (.RData, .rda, .rds)\cr 13 | #' * Common data formats (CSV, Excel, text)\cr 14 | #' * System and temporary files\cr 15 | #' * IDE-specific files 16 | #' 17 | #' @details 18 | #' If a \code{.gitignore} file already exists, the user will be prompted before any 19 | #' overwriting occurs. The template provides substantial security enhancements 20 | #' over basic \code{.gitignore} files. 21 | #' 22 | #' WARNING: Always consult your organization's data security team before using git 23 | #' with any sensitive or protected health information (PHI). This template helps 24 | #' prevent accidental data exposure but should not be considered a complete 25 | #' security solution. 26 | #' 27 | #' @examples 28 | #' # Create a temporary directory for testing 29 | #' tmp_dir <- tempdir() 30 | #' 31 | #' # Write the .gitignore file 32 | #' write_ignore(path = tmp_dir) 33 | #' 34 | #' # Confirm the file was created (optional, for user confirmation) 35 | #' file.exists(file.path(tmp_dir, ".gitignore")) 36 | #' 37 | #' # Clean up: Remove the created file 38 | #' unlink(file.path(tmp_dir, ".gitignore")) 39 | #' 40 | #' @export 41 | write_ignore <- function(path = here::here(), .initialize_proj = FALSE) { 42 | 43 | # Validate path 44 | if (is.null(path) || is.na(path) || !dir.exists(path)) { 45 | stop("Invalid `path`. Please enter a valid project directory.") 46 | } 47 | 48 | # Normalize the path for consistency 49 | path <- normalizePath(path, mustWork = TRUE) 50 | 51 | # Set up full destination file path 52 | the_ignore_file <- file.path(path, ".gitignore") 53 | 54 | # Handle ignore creation/overwrite 55 | if (file.exists(the_ignore_file)) { 56 | stop('A .gitignore file already exists in the specified path.' ) 57 | } 58 | 59 | # Get .gitignore template path 60 | template_path <- system.file("gists/gitignore", package = "froggeR") 61 | if (template_path == "") { 62 | stop("Could not find .gitignore template in package installation") 63 | } 64 | 65 | file.copy(from = template_path, to = the_ignore_file, overwrite = FALSE) 66 | ui_done("Created .gitignore") 67 | 68 | if (!.initialize_proj) usethis::edit_file(the_ignore_file) 69 | 70 | return(invisible(the_ignore_file)) 71 | } 72 | -------------------------------------------------------------------------------- /R/write_notes.R: -------------------------------------------------------------------------------- 1 | #' Create a project README file 2 | #' 3 | #' This function streamlines project documentation by creating a dated progress notes 4 | #' file. 5 | #' 6 | #' @inheritParams write_ignore 7 | #' 8 | #' @return CA chronological project progress notes tracker. 9 | #' @details 10 | #' The dated_progress_notes.md file is initialized with the current date and is designed 11 | #' to help track project milestones chronologically. If the progress notes file already 12 | #' exists, the function will stop and warn the user. 13 | #' 14 | #' @examples 15 | #' # Create a temporary directory for testing 16 | #' tmp_dir <- tempdir() 17 | #' 18 | #' # Write the progress notes file 19 | #' write_notes(path = tmp_dir) 20 | #' 21 | #' # Confirm the file was created (optional, for user confirmation) 22 | #' file.exists(file.path(tmp_dir, "dated_progress_notes.md")) 23 | #' 24 | #' # Clean up: Remove the created file 25 | #' unlink(file.path(tmp_dir, "dated_progress_notes.md")) 26 | #' 27 | #' @export 28 | write_notes <- function(path = here::here(), .initialize_proj = FALSE) { 29 | 30 | # Validate path 31 | if (is.null(path) || is.na(path) || !dir.exists(path)) { 32 | stop("Invalid `path`. Please enter a valid project directory.") 33 | } 34 | 35 | # Normalize the path for consistency 36 | path <- normalizePath(path, mustWork = TRUE) 37 | 38 | # Set up the full destination file path 39 | the_notes_file <- file.path(path, "dated_progress_notes.md") 40 | 41 | # Handle notes creation 42 | if (file.exists(the_notes_file)) { 43 | stop("A dated_progress_notes.md already exists in the specified path.") 44 | } 45 | 46 | # Write content 47 | progress_notes_content <- paste0( 48 | "# Project updates\n\n* ", 49 | format(Sys.Date(), "%b %d, %Y"), 50 | ": project started" 51 | ) 52 | 53 | writeLines(progress_notes_content, con = the_notes_file) 54 | ui_done("Created dated_progress_notes.md") 55 | 56 | if (!.initialize_proj) usethis::edit_file(the_notes_file) 57 | 58 | return(invisible(the_notes_file)) 59 | } -------------------------------------------------------------------------------- /R/write_quarto.R: -------------------------------------------------------------------------------- 1 | #' Create a New 'Quarto' Document 2 | #' 3 | #' This function creates a new 'Quarto' document (.qmd file) with either a custom 4 | #' or standard YAML header. When using a custom header, it integrates with 5 | #' `froggeR::settings()` for reusable metadata across documents. 6 | #' 7 | #' @inheritParams write_ignore 8 | #' @param filename Character string. The name of the file without the '.qmd' extension. 9 | #' Only letters, numbers, hyphens, and underscores are allowed. 10 | #' @param example Logical. If TRUE, creates a Quarto document with a default to 11 | #' position the brand logo and examples of within-document cross-referencing, links, 12 | #' and references. 13 | #' 14 | #' @return Invisibly returns NULL after creating the 'Quarto' document. 15 | #' 16 | #' @examples 17 | #' if (interactive()) { 18 | #' # Create a temporary directory for testing 19 | #' tmp_dir <- tempdir() 20 | #' 21 | #' # Write the Quarto & associated files for a custom YAML with reusable metadata 22 | #' write_quarto(path = tempdir(), filename = "analysis") 23 | #' 24 | #' # Write the Quarto file with a template requiring more DIY 25 | #' write_quarto(path = tempdir(), filename = "analysis_basic", example = FALSE) 26 | #' 27 | #' # Confirm the file was created (optional, for user confirmation) 28 | #' file.exists(file.path(tmp_dir, "analysis.qmd")) 29 | #' file.exists(file.path(tmp_dir, "analysis_basic.qmd")) 30 | #' 31 | #' # Clean up: Remove the created file 32 | #' unlink(list.files(tempdir(), full.names = TRUE), recursive = TRUE) 33 | #' } 34 | #' 35 | #' @export 36 | write_quarto <- function( 37 | filename = "Untitled-1", path = here::here(), 38 | example = FALSE, .initialize_proj = FALSE 39 | ) { 40 | 41 | # Validate path 42 | if (is.null(path) || is.na(path) || !dir.exists(path)) { 43 | stop("Invalid `path`. Please enter a valid project directory.") 44 | } 45 | 46 | # Validate filename 47 | if (!is.character(filename)) stop('Invalid filename: must be character.') 48 | if (!grepl('^[a-zA-Z0-9_-]+$', filename)) { 49 | stop('Invalid filename. Use only letters, numbers, hyphens, and underscores.') 50 | } 51 | 52 | # Normalize the path for consistency 53 | path <- normalizePath(path, mustWork = TRUE) 54 | 55 | # Set up full file path 56 | the_quarto_file <- file.path(path, paste0(filename, '.qmd')) 57 | 58 | # Check if Quarto doc exists 59 | if (file.exists(the_quarto_file)) { 60 | stop(sprintf("%s.qmd already exists in the specified path.", filename)) 61 | } 62 | 63 | # Handle custom YAML 64 | if (example) { 65 | 66 | # Project-level settings 67 | settings_file <- file.path(path, '_variables.yml') 68 | # Global froggeR settings 69 | config_path <- rappdirs::user_config_dir("froggeR") 70 | config_file <- file.path(config_path, "config.yml") 71 | 72 | # Do they exist? 73 | project_settings <- file.exists(settings_file) 74 | froggeR_settings <- file.exists(config_file) 75 | 76 | if (!.initialize_proj) { 77 | .check(config_file, project_settings, froggeR_settings) 78 | } else if (!froggeR_settings) { 79 | ui_oops(sprintf('No global %s config file found', col_green('froggeR'))) 80 | } 81 | 82 | if (!project_settings) { 83 | # The _variables.yml file will be created by using either: 84 | # 1) the ~/.config/froggeR/config.yml file --or-- 85 | # 2) the inst/gists/config.yml template 86 | write_variables(path = path, .initialize_proj = TRUE) 87 | 88 | # Now recheck that _variables.yml exists so the path gets all the necessary files 89 | if (file.exists(settings_file)) { 90 | project_settings <- TRUE 91 | 92 | } else { 93 | ui_oops( 94 | 'UH OH! Encoutered an unexpected snag while writing the `_variables.yml file.' 95 | ) 96 | message(sprintf( 97 | "\nSee %s and %s for more help.", 98 | col_green('?froggeR::write_variables'), 99 | col_green('?froggeR::write_quarto') 100 | )) 101 | # Reset for default template 102 | example <- FALSE 103 | } 104 | } 105 | 106 | if (project_settings && !.initialize_proj) { 107 | # Create _quarto.yml & SCSS if they do not exist 108 | # Use .initialize_project = TRUE here to silence & not open the files 109 | .ensure_auxiliary_files(path = path, .initialize_proj = TRUE) 110 | if (!file.exists(settings_file)) write_variables(path=path, .initialize_proj=TRUE) 111 | } 112 | } 113 | 114 | # Write the Quarto file based on template 115 | template_path <- if (example) { 116 | system.file('gists/custom_quarto.qmd', package = 'froggeR') 117 | } else { 118 | system.file('gists/basic_quarto.qmd', package = 'froggeR') 119 | } 120 | 121 | if (template_path == "") { 122 | stop("Could not find Quarto template in package installation") 123 | } 124 | 125 | file.copy(from = template_path, to = the_quarto_file, overwrite = FALSE) 126 | ui_done(sprintf( 127 | "Created %s.qmd %s", filename, ifelse(example, col_green("with examples"), "") 128 | )) 129 | 130 | # Open the file if... 131 | same_dir <- here::here() == path 132 | if (same_dir && !.initialize_proj && interactive()) usethis::edit_file(the_quarto_file) 133 | 134 | invisible(NULL) 135 | } 136 | -------------------------------------------------------------------------------- /R/write_readme.R: -------------------------------------------------------------------------------- 1 | #' Create a project README file 2 | #' 3 | #' This function streamlines project documentation by a README.md file. 4 | #' 5 | #' @inheritParams write_ignore 6 | #' 7 | #' @return Creates a comprehensive README template for project documentation. 8 | #' @details 9 | #' The README.md template includes structured sections for: 10 | #' \itemize{ 11 | #' \item Project description (study name, principal investigator, author) 12 | #' \item Project setup steps for reproducibility 13 | #' \item File and directory descriptions 14 | #' \item Miscellaneous project notes 15 | #' } 16 | #' 17 | #' @examples 18 | #' # Create a temporary directory for testing 19 | #' tmp_dir <- tempdir() 20 | #' 21 | #' # Write the README file 22 | #' write_readme(path = tmp_dir) 23 | #' 24 | #' # Confirm the file was created (optional, for user confirmation) 25 | #' file.exists(file.path(tmp_dir, "README.md")) 26 | #' 27 | #' # Clean up: Remove the created file 28 | #' unlink(file.path(tmp_dir, "README.md")) 29 | #' 30 | #' @export 31 | 32 | write_readme <- function(path = here::here(), .initialize_proj = FALSE) { 33 | 34 | # Validate path 35 | if (is.null(path) || is.na(path) || !dir.exists(path)) { 36 | stop("Invalid `path`. Please enter a valid project directory.") 37 | } 38 | 39 | # Normalize the path for consistency 40 | path <- normalizePath(path, mustWork = TRUE) 41 | 42 | # Set up the full destination path 43 | the_readme_file <- file.path(path, 'README.md') 44 | 45 | # Handle README creation 46 | if (file.exists(the_readme_file)) { 47 | stop('A README.md already exists in the specified path.') 48 | } 49 | 50 | # Get README template path 51 | readme_path <- system.file("gists/README.md", package = "froggeR") 52 | if (readme_path == "") { 53 | stop("Could not find README template in package installation") 54 | } 55 | 56 | file.copy(from = readme_path, to = the_readme_file, overwrite = TRUE) 57 | ui_done("Created README.md") 58 | 59 | if (!.initialize_proj) usethis::edit_file(the_readme_file) 60 | 61 | return(invisible(the_readme_file)) 62 | 63 | } -------------------------------------------------------------------------------- /R/write_scss.R: -------------------------------------------------------------------------------- 1 | #' Create a 'Quarto' SCSS file 2 | #' 3 | #' This function creates the \code{.scss} file so that any 'Quarto' project can be easily 4 | #' customized with SCSS styling variables, mixins, and rules. 5 | #' 6 | #' @inheritParams write_ignore 7 | #' 8 | #' @return A SCSS file to customize 'Quarto' styling. 9 | #' @details 10 | #' The function includes a robust YAML handling mechanism that safely adds new SCSS file. 11 | #' 12 | #' See \code{vignette("customizing-quarto", package = "froggeR")} vignette for more help. 13 | #' 14 | #' @examples 15 | #' # Create a temporary directory for testing 16 | #' tmp_dir <- tempdir() 17 | #' 18 | #' # Write the SCSS file 19 | #' write_scss(path = tmp_dir) 20 | #' 21 | #' # Confirm the file was created (optional, for user confirmation) 22 | #' file.exists(file.path(tmp_dir, "custom.scss")) 23 | #' 24 | #' # Clean up: Remove the created file 25 | #' unlink(file.path(tmp_dir, "custom.scss")) 26 | #' 27 | #' @export 28 | write_scss <- function(path = here::here(), .initialize_proj = FALSE) { 29 | 30 | # Validate path 31 | if (is.null(path) || is.na(path) || !dir.exists(path)) { 32 | stop("Invalid `path`. Please enter a valid project directory.") 33 | } 34 | 35 | # Normalize the path for consistency 36 | path <- normalizePath(path, mustWork = TRUE) 37 | 38 | # Set up full destination file path 39 | the_scss_file <- file.path(path, "custom.scss") 40 | 41 | # Handle custom.scss creation 42 | if (file.exists(the_scss_file)) { 43 | stop('A SCSS file already exists in the specified path.') 44 | } 45 | 46 | # Get scss template path 47 | template_path <- system.file("gists/custom.scss", package = "froggeR") 48 | if (template_path == "") { 49 | stop("Could not find SCSS template in package installation") 50 | } 51 | 52 | file.copy(from = template_path, to = the_scss_file, overwrite = FALSE) 53 | ui_done("Created custom.scss") 54 | 55 | if (!.initialize_proj) usethis::edit_file(the_scss_file) 56 | 57 | return(invisible(the_scss_file)) 58 | 59 | } 60 | -------------------------------------------------------------------------------- /R/write_variables.R: -------------------------------------------------------------------------------- 1 | #' Write Variables YAML for 'Quarto' Projects 2 | #' 3 | #' This function creates or updates the `_variables.yml` file in a Quarto project 4 | #' directory using froggeR settings, if they exist in the config path. 5 | #' 6 | #' @inheritParams write_ignore 7 | #' 8 | #' @return Invisibly returns `NULL` after creating or updating the `_variables.yml` file. 9 | #' @details 10 | #' The function will attempt to use the current froggeR settings from the config path. If 11 | #' no global configurations exist, a template `_variables.yml` will be created. 12 | #' 13 | #' @examples 14 | #' 15 | #' # Write the _variables.yml file 16 | #' if (interactive()) { 17 | #' temp_dir <- tempdir() 18 | #' write_variables(temp_dir) 19 | #' } 20 | #' 21 | #' @export 22 | write_variables <- function(path = here::here(), .initialize_proj = FALSE) { 23 | # Validate path 24 | if (is.null(path) || is.na(path) || !dir.exists(path)) { 25 | stop("Invalid `path`. Please enter a valid project directory.") 26 | } 27 | 28 | # Normalize the path for consistency 29 | path <- normalizePath(path, mustWork = TRUE) 30 | 31 | # Set up full destination file path 32 | the_variables_file <- file.path(path, '_variables.yml') 33 | 34 | # Handle _variables.yml creation 35 | if (file.exists(the_variables_file)) { 36 | stop('_variables.yml already exists in the specified path.') 37 | } 38 | 39 | # Global froggeR settings 40 | config_path <- rappdirs::user_config_dir("froggeR") 41 | config_file <- file.path(config_path, "config.yml") 42 | # Does it exist? 43 | froggeR_settings <- file.exists(config_file) 44 | 45 | # Write the config file based on template: if there's a .config/froggeR file, 46 | # use that or else use the template found here in the package 47 | template_path <- if (froggeR_settings) { 48 | # Display message if using the .config/froggeR/config.yml file 49 | ui_info(sprintf('Copying existing %s settings...', col_green('froggeR'))) 50 | config_file 51 | } else { 52 | system.file('gists/config.yml', package = 'froggeR') 53 | } 54 | 55 | if (template_path == "") { 56 | stop("Could not find config template in package installation") 57 | } 58 | 59 | file.copy(from = template_path, to = the_variables_file, overwrite = FALSE) 60 | ui_done("Created _variables.yml") 61 | 62 | if (!.initialize_proj) usethis::edit_file(the_variables_file) 63 | 64 | return(invisible(NULL)) 65 | } 66 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # froggeR 2 | 3 | 4 | [![R-CMD-check](https://img.shields.io/badge/R--CMD--check-passing-brightgreen)](https://github.com/kyleGrealis/froggeR) 5 | [![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#maturing) 6 | [![CRAN status](https://www.r-pkg.org/badges/version/froggeR)](https://CRAN.R-project.org/package=froggeR) 7 | [![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/froggeR)](https://cran.r-project.org/package=froggeR) 8 | 9 | > froggeR version: 0.5.2 10 | 11 | froggeR is an R package designed to streamline the creation and management of Quarto projects. It provides a suite of tools to automate setup, ensure consistency, and enhance collaboration in data science workflows. 12 | 13 | ## Why froggeR? 14 | 15 | > Leap ahead in your data science journey with froggeR! Streamline Quarto workflows, create structured projects, and enhance collaboration with ease. 🐸 16 | 17 | froggeR simplifies project setup so you can focus on what matters: 18 | 19 | * **Efficiency**: Minimize setup time, maximize analysis time 20 | * **Consistency**: Uniform styling and structure across all your projects 21 | * **Reliability**: Prevent common setup issues before they occur 22 | * **Security**: Robust `.gitignore` settings for enhanced data protection 23 | * **Collaboration**: Structured documentation for seamless team onboarding 24 | * **Customization**: Easy-to-use tools for tailoring project aesthetics 25 | * **Reproducibility**: Ensure consistent environments across team members 26 | 27 | ---- 28 | 29 | ## Key Features 30 | 31 | * One-command Quarto project initialization 32 | * Centralized settings management for consistent metadata 33 | * Quickly create, save, and reuse metadata & Quarto branding 34 | * Automated creation of essential project files (README, .gitignore, etc.) 35 | * Custom YAML and SCSS templating for unique document styling 36 | * Interactive setup process for user-specific configurations 37 | 38 | ---- 39 | 40 | ## Getting Started 41 | 42 | Install froggeR and create your first project in minutes: 43 | 44 | ```r 45 | # Install from CRAN... JUST APPROVED Jan. 15! 46 | install.packages("froggeR") 47 | 48 | # Or get the development version 49 | remotes::install_github('kyleGrealis/froggeR') 50 | 51 | # Create your first froggeR project 52 | froggeR::quarto_project('frogs') 53 | ``` 54 | ---- 55 | 56 | ## Who's it for? 57 | 58 | froggeR is ideal for R users who: 59 | 60 | * Manage multiple Quarto projects 61 | * Find themselves rewriting the same YAML & project structure repeatedly 62 | * Collaborate in team environments 63 | * Prioritize analysis over setup complexities 64 | * Need rapid project initialization 65 | 66 | ---- 67 | 68 |

69 | Rendered Document Example 70 |

71 |

Example of a rendered Quarto document created with froggeR

72 | 73 | 74 | ---- 75 | 76 | ### 🎯 Streamlined Quarto Project Creation 77 | 78 | Initialize a comprehensive Quarto project with a single command: 79 | 80 | ```r 81 | froggeR::quarto_project(name = 'my_new_project') 82 | ``` 83 | 84 | This creates: 85 | 86 | * A Quarto document with custom YAML 87 | * A comprehensive `.gitignore` 88 | * Structured `README.md` & progress notes templates 89 | * Reusable `_variables.yml` & `_brand.yml` files 90 | * A `custom.scss` style sheet template 91 | * A `references.bib` for citations 92 | 93 | ### 🔄 Centralized Settings Management 94 | 95 | Maintain consistent metadata across your documents: 96 | 97 | ```r 98 | froggeR::settings() 99 | ``` 100 | 101 | Interactively create or update metadata that is reusable across Quarto projects & 102 | documents with: 103 | 104 | * Author details 105 | * Contact information 106 | * Affiliations 107 | * Project metadata 108 | * Document preferences 109 | 110 | ### 📝 Templated Quarto Documents 111 | 112 | Quickly generate new Quarto documents with pre-formatted headers: 113 | 114 | ```r 115 | froggeR::write_quarto( 116 | filename = 'data_cleaning', 117 | example = TRUE # Add tool templates 118 | ) 119 | ``` 120 | 121 | ### 🛡️ Enhanced Git Protection 122 | 123 | Set up a comprehensive `.gitignore` for R projects: 124 | 125 | ```r 126 | froggeR::write_ignore() 127 | ``` 128 | 129 | Automatically excludes: 130 | 131 | * R data files (`.RData`, `.rda`, `.rds`) 132 | * Common data formats (CSV, Excel, text files) 133 | * Sensitive information 134 | 135 | ### 🌟 Custom Styling Made Easy 136 | 137 | Generate a SCSS template for custom document styling: 138 | 139 | ```r 140 | froggeR::write_scss() 141 | ``` 142 | 143 | Provides a formatted stylesheet with: 144 | 145 | * SCSS defaults 146 | * SCSS mixins 147 | * SCSS rules 148 | 149 | Customize your document's appearance by uncommenting desired styles. 150 | 151 | ### 📚 Automated Project Documentation 152 | 153 | Generate a structured README for your project: 154 | 155 | ```r 156 | froggeR::write_readme() 157 | ``` 158 | 159 | Includes sections for: 160 | 161 | * Project overview 162 | * Setup instructions 163 | * File and directory explanations 164 | * Contribution guidelines 165 | 166 | ---- 167 | 168 | ## Comparison with Other Tools 169 | 170 | While there are other project management tools for R, froggeR stands out by: 171 | 172 | * Focusing specifically on Quarto workflows 173 | * Providing a balance between automation and customization 174 | * Offering a comprehensive suite of tools in a single package 175 | * Emphasizing reproducibility and collaboration 176 | 177 | ---- 178 | 179 | We're constantly improving froggeR. Upcoming features include: 180 | 181 | * Quarto dashboard integration 182 | * Integration with version control systems 183 | * Enhanced team collaboration tools 184 | * More customizable templates for various data science workflows 185 | 186 | ---- 187 | 188 | ## Function Reference 189 | 190 | | Function | Description | 191 | |----------|-------------| 192 | | `settings()` | Manage persistent Quarto document metadata | 193 | | `quarto_project()` | Initialize a complete Quarto project structure | 194 | | `write_quarto()`\* | Create consistently formatted Quarto documents | 195 | | `write_variables()`\* | Re-use metadata across projects & documents | 196 | | `save_variables()` | Save current `_variables.yml` to system-level configs | 197 | | `save_brand()` | Save current `_brand.yml` to system-level configs | 198 | | `write_brand()` | Create project-level `_brand.yml` configs | 199 | | `write_ignore()`\* | Configure `.gitignore` for enhanced data security | 200 | | `write_readme()`\* | Generate a comprehensive project README | 201 | | `write_notes()`\* | Create a dated progress notes template | 202 | | `write_scss()`\* | Create a customizable SCSS styling template | 203 | \* *These functions are included with `quarto_project()`* 204 | 205 | ---- 206 | 207 | ## Contributing 208 | 209 | We're open to suggestions! If you have ideas for new features, please open an issue on our GitHub repository. 210 | 211 | ---- 212 | 213 | ## License 214 | 215 | [MIT](https://choosealicense.com/licenses/mit/) 216 | 217 | --- 218 | 219 | Developed by [Kyle Grealis](https://github.com/kyleGrealis) 220 | -------------------------------------------------------------------------------- /inst/WORDLIST: -------------------------------------------------------------------------------- 1 | CMD 2 | Customizations 3 | Lifecycle 4 | Mixins 5 | ORCID 6 | Pre 7 | Preconfigured 8 | RData 9 | README 10 | SCSS 11 | TOC 12 | Templated 13 | Uncomment 14 | customizations 15 | effeciency 16 | froggeR's 17 | gitignore 18 | md 19 | minimalistic 20 | mixins 21 | modularity 22 | onboarding 23 | pkgdown 24 | pre 25 | qmd 26 | rda 27 | rds 28 | reinput 29 | roadmap 30 | roxygen 31 | stylesheet 32 | templating 33 | uncommenting 34 | yml 35 | ️ 36 | -------------------------------------------------------------------------------- /inst/gists/README.md: -------------------------------------------------------------------------------- 1 | # Repository Name 2 | 3 | **Code Author**: 4 | 5 | **Description**: 6 | 7 | **Purpose**: 8 | 9 | ## Directories 10 | 11 | `path`: what goes in the directory 12 | 13 | ## File Descriptions 14 | 15 | 1. 16 | 2. 17 | 3. 18 | -------------------------------------------------------------------------------- /inst/gists/basic_quarto.qmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "" 3 | date: last-modified 4 | --- 5 | 6 | -------------------------------------------------------------------------------- /inst/gists/brand.yml: -------------------------------------------------------------------------------- 1 | # meta: 2 | # name: Company Name 3 | # link: 4 | # home: https://example.com 5 | 6 | # logo: 7 | # large: logos/logo-1.png # use a path location or add a URL 8 | # medium: 9 | # small: 10 | 11 | # color: 12 | # palette: 13 | # green: "#005030" 14 | # orange: "#f47321" 15 | # gray: "#f9f9f9" 16 | 17 | # typography: 18 | # fonts: 19 | # - family: Comic Sans 20 | # source: bunny # or google or path to font file 21 | # - family: Fira Code 22 | # source: bunny 23 | 24 | # base: Comic Sans 25 | # headings: 26 | # color: green 27 | # monospace: Fira Code 28 | # monospace-inline: 29 | # color: green 30 | # background-color: gray 31 | # link: 32 | # color: green -------------------------------------------------------------------------------- /inst/gists/config.yml: -------------------------------------------------------------------------------- 1 | # You do not need to use quotes around values. 2 | # You may edit any value or leave it blank. 3 | name: 4 | email: 5 | orcid: 6 | url: #https://example.com 7 | affiliations: 8 | 9 | -------------------------------------------------------------------------------- /inst/gists/custom.scss: -------------------------------------------------------------------------------- 1 | /*-- scss:defaults --*/ 2 | // Colors 3 | // $primary: #2c365e; 4 | // $body-bg: #fefefe; 5 | 6 | 7 | /*-- scss:mixins --*/ 8 | 9 | 10 | /*-- scss:rules --*/ 11 | // Custom theme rules 12 | 13 | // .title-block { 14 | // margin-bottom: 2rem; 15 | // border-bottom: 3px solid $primary; 16 | // } 17 | 18 | // code { 19 | // color: darken($primary, 10%); 20 | // padding: 0.2em 0.4em; 21 | // border-radius: 3px; 22 | // } 23 | 24 | // Center images 25 | // img { 26 | // width: 50%; 27 | // height: auto; 28 | // display: block; 29 | // margin: 0 auto; 30 | // } 31 | 32 | // Set the ORCID logo to return to being on the same line as the author. 33 | // When first adding this custom.scss with _brand.yml, the logo was shifted down. 34 | // This section corrects that & returns the icon to the original location. 35 | #title-block-header.quarto-title-block.default .quarto-title-author-orcid img { 36 | margin-top: -1.2em; 37 | height: 0.8em; 38 | width: 0.8em; 39 | } 40 | 41 | // Add a hover effect to links within the document body only. 42 | section p a:hover { 43 | // color: $orange; 44 | text-decoration: none; 45 | } 46 | -------------------------------------------------------------------------------- /inst/gists/custom_quarto.qmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "" 3 | date: last-modified 4 | --- 5 | 6 | --- 7 | 8 | {{< brand logo large >}} 9 | 10 | ## Section {#sec-one} 11 | 12 | ```{r} 13 | #| label: setup 14 | #| eval: true 15 | suppressPackageStartupMessages(library(tidyverse)) 16 | mtcars |> 17 | filter(cyl >= 6) |> 18 | head() 19 | ``` 20 | 21 | ## The saga continues {#sec-the-saga} 22 | 23 | Let's add a [link here](https://example.com) 24 | 25 | ::: {.column-margin} 26 | Hey, from the side! 27 | ::: 28 | 29 | And now adding a section link to @sec-the-saga. 30 | 31 | As described by @grealis, something `happened`. 32 | 33 | [This will appear on the side as an "aside" in the margin without a footnote.]{.aside} -------------------------------------------------------------------------------- /inst/gists/gitignore: -------------------------------------------------------------------------------- 1 | # Version 2024-05-18 2 | 3 | # History files 4 | .Rhistory 5 | .Rapp.history 6 | 7 | # Session Data files 8 | .RData 9 | *.RData 10 | .RDataTmp 11 | 12 | # User-specific files 13 | .Ruserdata 14 | 15 | # Example code in package build process 16 | *-Ex.R 17 | 18 | # Output files from R CMD build 19 | /*.tar.gz 20 | 21 | # Output files from R CMD check 22 | /*.Rcheck/ 23 | 24 | # RStudio files 25 | .Rproj.user 26 | .Rproj.user/ 27 | 28 | # produced vignettes 29 | vignettes/*.html 30 | vignettes/*.pdf 31 | 32 | # OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3 33 | .httr-oauth 34 | 35 | # knitr and R markdown default cache directories 36 | *_cache/ 37 | /cache/ 38 | 39 | # Temporary files created by R markdown 40 | *.utf8.md 41 | *.knit.md 42 | 43 | # R Environment Variables 44 | .Renviron 45 | 46 | # Mac 47 | .DS_Store 48 | .Thumbs.db 49 | Thumbs.db 50 | 51 | # Directories 52 | docs/ 53 | data/ 54 | development/ 55 | macros/ 56 | output/ 57 | sasdata/ 58 | libs/ 59 | 60 | # translation temp files 61 | po/*~ 62 | 63 | # RStudio Connect folder 64 | rsconnect/ 65 | 66 | ### R.Bookdown Stack ### 67 | # R package: bookdown caching files 68 | /*_files/ 69 | 70 | 71 | # Exclude .Rmd output 72 | *.html 73 | **/figure-html/ 74 | 75 | # Exclude Text 76 | *.txt 77 | *.Txt 78 | *.TXT 79 | 80 | # Exclude Excel 81 | *.xlsx 82 | *.xls 83 | 84 | # R data 85 | *.rds 86 | *.RDS 87 | *.Rds 88 | *.rda 89 | *.RDA 90 | *.Rda 91 | 92 | # csv data 93 | *.csv 94 | *.CSV 95 | *.Csv 96 | 97 | # sas data 98 | *.sas7bdat 99 | *.sas7bcat 100 | 101 | # SPSS data 102 | *.sav 103 | *.SAV 104 | *.Sav 105 | 106 | # SPSS output 107 | *.spv 108 | *.SPV 109 | *.Spv 110 | 111 | # STATA data 112 | *.dta 113 | *.DTA 114 | *.Dta 115 | 116 | # STATA log files 117 | *.log 118 | *.LOG 119 | *.Log 120 | *.smcl 121 | *.SMCL 122 | *.Smcl 123 | 124 | # data commonly used in Python 125 | *.json 126 | *.pkl 127 | *.h5 128 | *.msgpack 129 | *.parquet 130 | *.feather 131 | 132 | # VSC 133 | www/.vscode/ 134 | 135 | # Bookdown book 136 | _book/ 137 | _bookdown_files/ 138 | 139 | # Binary - Powerpoint and iThoughtsX 140 | *.ppt 141 | *.pptx 142 | *.itmz 143 | 144 | # R packages 145 | *.tar 146 | 147 | # Archives 148 | *.zip 149 | *.Zip 150 | *.ZIP 151 | 152 | # Quarto 153 | /.quarto/ 154 | /_site/ 155 | .quarto/ 156 | _site/ 157 | -------------------------------------------------------------------------------- /inst/gists/quarto.yml: -------------------------------------------------------------------------------- 1 | project: 2 | title: "" 3 | type: default 4 | 5 | author: 6 | - name: "{{< var name >}}" 7 | url: "{{< var url >}}" 8 | email: "{{< var email >}}" 9 | orcid: "{{< var orcid >}}" 10 | roles: "{{< var roles >}}" 11 | affiliations: "{{< var affiliations >}}" 12 | corresponding: true 13 | 14 | abstract: "" 15 | 16 | format: 17 | html: 18 | embed-resources: true 19 | theme: 20 | - default 21 | - _brand.yml 22 | - custom.scss 23 | toc: true 24 | toc-location: left 25 | code-tools: true 26 | code-copy: true 27 | code-fold: true 28 | code-summary: "Show the code" 29 | page-layout: article 30 | link-external-newwindow: true 31 | 32 | # Other formats 33 | # docx: default 34 | # pdf: default 35 | 36 | # Uncomment to add browser tab favicon 37 | # include-in-header: 38 | # text: | 39 | # 40 | 41 | number-sections: false 42 | 43 | bibliography: references.bib 44 | 45 | editor: source -------------------------------------------------------------------------------- /inst/gists/references.bib: -------------------------------------------------------------------------------- 1 | @article{grealis, 2 | author = {Grealis, Kyle}, 3 | title = {What am I Doing?}, 4 | year = {2025}, 5 | issue_date = {June 2025}, 6 | publisher = {Azimuth Project Printing & Design}, 7 | address = {USA}, 8 | volume = {6}, 9 | number = {1}, 10 | issn = {123-456}, 11 | url = {https://doi.org/000/000}, 12 | doi = {07.30.2021}, 13 | journal = {Quarto is Fun}, 14 | month = june, 15 | pages = {21-26}, 16 | numpages = {5} 17 | } -------------------------------------------------------------------------------- /man/figures/code_block_after.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/code_block_after.png -------------------------------------------------------------------------------- /man/figures/code_block_before.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/code_block_before.png -------------------------------------------------------------------------------- /man/figures/config-file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/config-file.png -------------------------------------------------------------------------------- /man/figures/custom-scss-file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/custom-scss-file.png -------------------------------------------------------------------------------- /man/figures/custom-yaml-init.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/custom-yaml-init.png -------------------------------------------------------------------------------- /man/figures/custom-yaml-rendered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/custom-yaml-rendered.png -------------------------------------------------------------------------------- /man/figures/document_types.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/document_types.png -------------------------------------------------------------------------------- /man/figures/froggeR-init.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/froggeR-init.png -------------------------------------------------------------------------------- /man/figures/froggeR_logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | froggeR 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | -------------------------------------------------------------------------------- /man/figures/frogger_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/frogger_logo.png -------------------------------------------------------------------------------- /man/figures/key-value.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/key-value.png -------------------------------------------------------------------------------- /man/figures/link_color_after.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/link_color_after.png -------------------------------------------------------------------------------- /man/figures/link_color_before.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/link_color_before.png -------------------------------------------------------------------------------- /man/figures/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/logo.png -------------------------------------------------------------------------------- /man/figures/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | froggeR 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | -------------------------------------------------------------------------------- /man/figures/new-froggeR-session.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/new-froggeR-session.png -------------------------------------------------------------------------------- /man/figures/project_init.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/project_init.png -------------------------------------------------------------------------------- /man/figures/project_structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/project_structure.png -------------------------------------------------------------------------------- /man/figures/project_yaml.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/project_yaml.png -------------------------------------------------------------------------------- /man/figures/settings-options.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/settings-options.png -------------------------------------------------------------------------------- /man/figures/variables-init.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/variables-init.png -------------------------------------------------------------------------------- /man/figures/variables-yml.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/variables-yml.png -------------------------------------------------------------------------------- /man/figures/write-quarto-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/write-quarto-example.png -------------------------------------------------------------------------------- /man/figures/yaml-comparison.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/man/figures/yaml-comparison.png -------------------------------------------------------------------------------- /man/quarto_project.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/quarto_project.R 3 | \name{quarto_project} 4 | \alias{quarto_project} 5 | \title{Create a Custom 'Quarto' Project} 6 | \usage{ 7 | quarto_project(name, path = here::here(), example = TRUE) 8 | } 9 | \arguments{ 10 | \item{name}{Character string. The name of the 'Quarto' project directory and 11 | initial \code{.qmd} file.} 12 | 13 | \item{path}{Character string. Path to the project directory.} 14 | 15 | \item{example}{Logical. If TRUE (default), creates a Quarto document with a default to 16 | position the brand logo and examples of within-document cross-referencing, links, 17 | and references.} 18 | } 19 | \value{ 20 | Invisibly returns the path to the created project directory. 21 | } 22 | \description{ 23 | This function creates a new 'Quarto' project directory with additional froggeR 24 | features. It first calls \code{quarto::quarto_create_project()} to set up the 25 | basic structure, then enhances it with froggeR-specific files and settings. 26 | } 27 | \details{ 28 | This function creates a 'Quarto' project with the following enhancements: 29 | \itemize{ 30 | \item \code{_brand.yml}: Stores Quarto project branding 31 | \item \code{logos}: Quarto project branding logos directory 32 | \item \code{_variables.yml}: Stores reusable YAML variables 33 | \item \code{.gitignore}: Enhanced settings for R projects 34 | \item \code{README.md}: Template README file 35 | \item \code{dated_progress_notes.md}: For project progress tracking 36 | \item \code{custom.scss}: Custom 'Quarto' styling 37 | } 38 | If froggeR settings don't exist, it will prompt to create them. 39 | } 40 | \examples{ 41 | if (interactive() && quarto::quarto_version() >= "1.6") { 42 | 43 | # Create the Quarto project with custom YAML & associated files 44 | quarto_project("frogs", path = tempdir(), example = TRUE) 45 | 46 | # Confirms files were created (optional, for user confirmation) 47 | file.exists(file.path(tempdir(), "frogs.qmd")) # Quarto doc 48 | file.exists(file.path(tempdir(), "_quarto.yml")) # project YAML file 49 | 50 | # Create a new Quarto project with standard Quarto (no examples) 51 | # quarto_project('frogs_standard', path = tempdir(), example = FALSE) 52 | 53 | } 54 | 55 | } 56 | \seealso{ 57 | \code{\link{write_quarto}}, \code{\link{settings}} 58 | } 59 | -------------------------------------------------------------------------------- /man/save_brand.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/save_brand.R 3 | \name{save_brand} 4 | \alias{save_brand} 5 | \title{Save brand YAML for 'Quarto' Projects} 6 | \usage{ 7 | save_brand(save_logos = TRUE) 8 | } 9 | \arguments{ 10 | \item{save_logos}{Logical. Save brand logos from `logos` directory. Default is `TRUE`.} 11 | } 12 | \value{ 13 | Invisibly returns `NULL` after creating system-level configuration file. 14 | } 15 | \description{ 16 | This function saves the current `_brand.yml` file from an existing froggeR 17 | Quarto project. This provides a safety catch to prevent unintended overwrite if the 18 | system-level configuration file exists. 19 | } 20 | \details{ 21 | The function will attempt to create a system-level configuration file from the current 22 | froggeR Quarto project. If the system-level configuration file already exists, the 23 | user will be prompted prior to overwrite. 24 | } 25 | \examples{ 26 | 27 | # Write the _brand.yml file 28 | if (interactive()) save_brand() 29 | 30 | } 31 | -------------------------------------------------------------------------------- /man/save_variables.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/save_variables.R 3 | \name{save_variables} 4 | \alias{save_variables} 5 | \title{Save variables YAML for 'Quarto' Projects} 6 | \usage{ 7 | save_variables() 8 | } 9 | \value{ 10 | Invisibly returns `NULL` after creating system-level configuration file. 11 | } 12 | \description{ 13 | This function saves the current `_variables.yml` file from an existing froggeR 14 | Quarto project. This provides a safety catch to prevent unintended overwrite if the 15 | system-level configuration file exists. 16 | } 17 | \details{ 18 | The function will attempt to create a system-level configuration file from the current 19 | froggeR Quarto project. If the system-level configuration file already exists, the 20 | user will be prompted prior to overwrite. 21 | } 22 | \examples{ 23 | 24 | # Write the _variables.yml file 25 | if (interactive()) save_variables() 26 | 27 | } 28 | -------------------------------------------------------------------------------- /man/settings.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/settings.R 3 | \name{settings} 4 | \alias{settings} 5 | \title{Manage 'froggeR' Settings} 6 | \usage{ 7 | settings() 8 | } 9 | \value{ 10 | No return value; called for side-effects. 11 | } 12 | \description{ 13 | This function provides useful instructions and information regarding `froggeR` 14 | settings. 15 | } 16 | \details{ 17 | This function can only run in an interactive environment. Choose to: 18 | - Check for the existence of project- and global-level configuration files 19 | - Display current project-level settings 20 | - Feedback for updating settings 21 | - Instructions how to reuse settings across multiple `froggeR` Quarto projects. 22 | } 23 | \examples{ 24 | # Only run in an interactive environment 25 | if (interactive()) froggeR::settings() 26 | 27 | } 28 | -------------------------------------------------------------------------------- /man/write_brand.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/write_brand.R 3 | \name{write_brand} 4 | \alias{write_brand} 5 | \title{Write Brand YAML for 'Quarto' Projects} 6 | \usage{ 7 | write_brand( 8 | path = here::here(), 9 | restore_logos = TRUE, 10 | .initialize_proj = FALSE 11 | ) 12 | } 13 | \arguments{ 14 | \item{path}{Character string. Path to the project directory.} 15 | 16 | \item{restore_logos}{Logical. Restore logo content from system configuration. 17 | Default is `TRUE`.} 18 | 19 | \item{.initialize_proj}{Logical. TRUE only if starting a 20 | \code{froggeR::quarto_project()}.} 21 | } 22 | \value{ 23 | Invisibly returns `NULL` after creating or updating the `_brand.yml` file. 24 | } 25 | \description{ 26 | This function creates or updates the `_brand.yml` file in a Quarto project 27 | directory if they exist in the config path. 28 | } 29 | \details{ 30 | The function will attempt to use the current froggeR settings from the config path. If 31 | no global configurations exist, a template `_brand.yml` will be created. 32 | } 33 | \examples{ 34 | 35 | # Write the _brand.yml file 36 | if (interactive()) { 37 | temp_dir <- tempdir() 38 | write_brand(temp_dir) 39 | } 40 | 41 | } 42 | -------------------------------------------------------------------------------- /man/write_ignore.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/write_ignore.R 3 | \name{write_ignore} 4 | \alias{write_ignore} 5 | \title{Create an enhanced \code{.gitignore} file} 6 | \usage{ 7 | write_ignore(path = here::here(), .initialize_proj = FALSE) 8 | } 9 | \arguments{ 10 | \item{path}{Character string. Path to the project directory.} 11 | 12 | \item{.initialize_proj}{Logical. TRUE only if starting a 13 | \code{froggeR::quarto_project()}.} 14 | } 15 | \value{ 16 | A \code{.gitignore} file with enhanced security rules. The file includes:\cr 17 | * R data files (.RData, .rda, .rds)\cr 18 | * Common data formats (CSV, Excel, text)\cr 19 | * System and temporary files\cr 20 | * IDE-specific files 21 | } 22 | \description{ 23 | This function creates a \code{.gitignore} file with enhanced security 24 | measures designed to help prevent accidental data leaks. The template includes 25 | comprehensive rules for common data file types and sensitive information. 26 | } 27 | \details{ 28 | If a \code{.gitignore} file already exists, the user will be prompted before any 29 | overwriting occurs. The template provides substantial security enhancements 30 | over basic \code{.gitignore} files. 31 | 32 | WARNING: Always consult your organization's data security team before using git 33 | with any sensitive or protected health information (PHI). This template helps 34 | prevent accidental data exposure but should not be considered a complete 35 | security solution. 36 | } 37 | \examples{ 38 | # Create a temporary directory for testing 39 | tmp_dir <- tempdir() 40 | 41 | # Write the .gitignore file 42 | write_ignore(path = tmp_dir) 43 | 44 | # Confirm the file was created (optional, for user confirmation) 45 | file.exists(file.path(tmp_dir, ".gitignore")) 46 | 47 | # Clean up: Remove the created file 48 | unlink(file.path(tmp_dir, ".gitignore")) 49 | 50 | } 51 | -------------------------------------------------------------------------------- /man/write_notes.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/write_notes.R 3 | \name{write_notes} 4 | \alias{write_notes} 5 | \title{Create a project README file} 6 | \usage{ 7 | write_notes(path = here::here(), .initialize_proj = FALSE) 8 | } 9 | \arguments{ 10 | \item{path}{Character string. Path to the project directory.} 11 | 12 | \item{.initialize_proj}{Logical. TRUE only if starting a 13 | \code{froggeR::quarto_project()}.} 14 | } 15 | \value{ 16 | CA chronological project progress notes tracker. 17 | } 18 | \description{ 19 | This function streamlines project documentation by creating a dated progress notes 20 | file. 21 | } 22 | \details{ 23 | The dated_progress_notes.md file is initialized with the current date and is designed 24 | to help track project milestones chronologically. If the progress notes file already 25 | exists, the function will stop and warn the user. 26 | } 27 | \examples{ 28 | # Create a temporary directory for testing 29 | tmp_dir <- tempdir() 30 | 31 | # Write the progress notes file 32 | write_notes(path = tmp_dir) 33 | 34 | # Confirm the file was created (optional, for user confirmation) 35 | file.exists(file.path(tmp_dir, "dated_progress_notes.md")) 36 | 37 | # Clean up: Remove the created file 38 | unlink(file.path(tmp_dir, "dated_progress_notes.md")) 39 | 40 | } 41 | -------------------------------------------------------------------------------- /man/write_quarto.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/write_quarto.R 3 | \name{write_quarto} 4 | \alias{write_quarto} 5 | \title{Create a New 'Quarto' Document} 6 | \usage{ 7 | write_quarto( 8 | filename = "Untitled-1", 9 | path = here::here(), 10 | example = FALSE, 11 | .initialize_proj = FALSE 12 | ) 13 | } 14 | \arguments{ 15 | \item{filename}{Character string. The name of the file without the '.qmd' extension. 16 | Only letters, numbers, hyphens, and underscores are allowed.} 17 | 18 | \item{path}{Character string. Path to the project directory.} 19 | 20 | \item{example}{Logical. If TRUE, creates a Quarto document with a default to 21 | position the brand logo and examples of within-document cross-referencing, links, 22 | and references.} 23 | 24 | \item{.initialize_proj}{Logical. TRUE only if starting a 25 | \code{froggeR::quarto_project()}.} 26 | } 27 | \value{ 28 | Invisibly returns NULL after creating the 'Quarto' document. 29 | } 30 | \description{ 31 | This function creates a new 'Quarto' document (.qmd file) with either a custom 32 | or standard YAML header. When using a custom header, it integrates with 33 | `froggeR::settings()` for reusable metadata across documents. 34 | } 35 | \examples{ 36 | if (interactive()) { 37 | # Create a temporary directory for testing 38 | tmp_dir <- tempdir() 39 | 40 | # Write the Quarto & associated files for a custom YAML with reusable metadata 41 | write_quarto(path = tempdir(), filename = "analysis") 42 | 43 | # Write the Quarto file with a template requiring more DIY 44 | write_quarto(path = tempdir(), filename = "analysis_basic", example = FALSE) 45 | 46 | # Confirm the file was created (optional, for user confirmation) 47 | file.exists(file.path(tmp_dir, "analysis.qmd")) 48 | file.exists(file.path(tmp_dir, "analysis_basic.qmd")) 49 | 50 | # Clean up: Remove the created file 51 | unlink(list.files(tempdir(), full.names = TRUE), recursive = TRUE) 52 | } 53 | 54 | } 55 | -------------------------------------------------------------------------------- /man/write_readme.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/write_readme.R 3 | \name{write_readme} 4 | \alias{write_readme} 5 | \title{Create a project README file} 6 | \usage{ 7 | write_readme(path = here::here(), .initialize_proj = FALSE) 8 | } 9 | \arguments{ 10 | \item{path}{Character string. Path to the project directory.} 11 | 12 | \item{.initialize_proj}{Logical. TRUE only if starting a 13 | \code{froggeR::quarto_project()}.} 14 | } 15 | \value{ 16 | Creates a comprehensive README template for project documentation. 17 | } 18 | \description{ 19 | This function streamlines project documentation by a README.md file. 20 | } 21 | \details{ 22 | The README.md template includes structured sections for: 23 | \itemize{ 24 | \item Project description (study name, principal investigator, author) 25 | \item Project setup steps for reproducibility 26 | \item File and directory descriptions 27 | \item Miscellaneous project notes 28 | } 29 | } 30 | \examples{ 31 | # Create a temporary directory for testing 32 | tmp_dir <- tempdir() 33 | 34 | # Write the README file 35 | write_readme(path = tmp_dir) 36 | 37 | # Confirm the file was created (optional, for user confirmation) 38 | file.exists(file.path(tmp_dir, "README.md")) 39 | 40 | # Clean up: Remove the created file 41 | unlink(file.path(tmp_dir, "README.md")) 42 | 43 | } 44 | -------------------------------------------------------------------------------- /man/write_scss.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/write_scss.R 3 | \name{write_scss} 4 | \alias{write_scss} 5 | \title{Create a 'Quarto' SCSS file} 6 | \usage{ 7 | write_scss(path = here::here(), .initialize_proj = FALSE) 8 | } 9 | \arguments{ 10 | \item{path}{Character string. Path to the project directory.} 11 | 12 | \item{.initialize_proj}{Logical. TRUE only if starting a 13 | \code{froggeR::quarto_project()}.} 14 | } 15 | \value{ 16 | A SCSS file to customize 'Quarto' styling. 17 | } 18 | \description{ 19 | This function creates the \code{.scss} file so that any 'Quarto' project can be easily 20 | customized with SCSS styling variables, mixins, and rules. 21 | } 22 | \details{ 23 | The function includes a robust YAML handling mechanism that safely adds new SCSS file. 24 | 25 | See \code{vignette("customizing-quarto", package = "froggeR")} vignette for more help. 26 | } 27 | \examples{ 28 | # Create a temporary directory for testing 29 | tmp_dir <- tempdir() 30 | 31 | # Write the SCSS file 32 | write_scss(path = tmp_dir) 33 | 34 | # Confirm the file was created (optional, for user confirmation) 35 | file.exists(file.path(tmp_dir, "custom.scss")) 36 | 37 | # Clean up: Remove the created file 38 | unlink(file.path(tmp_dir, "custom.scss")) 39 | 40 | } 41 | -------------------------------------------------------------------------------- /man/write_variables.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/write_variables.R 3 | \name{write_variables} 4 | \alias{write_variables} 5 | \title{Write Variables YAML for 'Quarto' Projects} 6 | \usage{ 7 | write_variables(path = here::here(), .initialize_proj = FALSE) 8 | } 9 | \arguments{ 10 | \item{path}{Character string. Path to the project directory.} 11 | 12 | \item{.initialize_proj}{Logical. TRUE only if starting a 13 | \code{froggeR::quarto_project()}.} 14 | } 15 | \value{ 16 | Invisibly returns `NULL` after creating or updating the `_variables.yml` file. 17 | } 18 | \description{ 19 | This function creates or updates the `_variables.yml` file in a Quarto project 20 | directory using froggeR settings, if they exist in the config path. 21 | } 22 | \details{ 23 | The function will attempt to use the current froggeR settings from the config path. If 24 | no global configurations exist, a template `_variables.yml` will be created. 25 | } 26 | \examples{ 27 | 28 | # Write the _variables.yml file 29 | if (interactive()) { 30 | temp_dir <- tempdir() 31 | write_variables(temp_dir) 32 | } 33 | 34 | } 35 | -------------------------------------------------------------------------------- /pkgdown/_pkgdown.yml: -------------------------------------------------------------------------------- 1 | url: https://www.kyleGrealis.com/froggeR/ 2 | template: 3 | bootstrap: 5 4 | light-switch: true 5 | bslib: 6 | font-size: 0.9rem 7 | border-radius: 0.5rem 8 | btn-border-radius: 0.25rem 9 | 10 | articles: 11 | - title: Get Started 12 | navbar: ~ 13 | contents: 14 | - hopping-into-quarto 15 | - quarto-workflow 16 | - customizing-quarto 17 | 18 | reference: 19 | - title: "Project Setup" 20 | desc: "Functions for creating and configuring Quarto projects" 21 | contents: 22 | - quarto_project 23 | - settings 24 | - save_variables 25 | - save_brand 26 | - title: "Document Creation" 27 | desc: "Functions for creating and styling Quarto documents" 28 | contents: 29 | - write_quarto 30 | - write_variables 31 | - write_brand 32 | - write_scss 33 | - title: "Project Documentation" 34 | desc: "Functions for enhancing project documentation and security" 35 | contents: 36 | - write_readme 37 | - write_notes 38 | - write_ignore 39 | -------------------------------------------------------------------------------- /pkgdown/favicon/apple-touch-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/pkgdown/favicon/apple-touch-icon.png -------------------------------------------------------------------------------- /pkgdown/favicon/favicon-96x96.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/pkgdown/favicon/favicon-96x96.png -------------------------------------------------------------------------------- /pkgdown/favicon/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/pkgdown/favicon/favicon.ico -------------------------------------------------------------------------------- /pkgdown/favicon/favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | froggeR 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | -------------------------------------------------------------------------------- /pkgdown/favicon/site.webmanifest: -------------------------------------------------------------------------------- 1 | { 2 | "name": "", 3 | "short_name": "", 4 | "icons": [ 5 | { 6 | "src": "/web-app-manifest-192x192.png", 7 | "sizes": "192x192", 8 | "type": "image/png", 9 | "purpose": "maskable" 10 | }, 11 | { 12 | "src": "/web-app-manifest-512x512.png", 13 | "sizes": "512x512", 14 | "type": "image/png", 15 | "purpose": "maskable" 16 | } 17 | ], 18 | "theme_color": "#ffffff", 19 | "background_color": "#ffffff", 20 | "display": "standalone" 21 | } -------------------------------------------------------------------------------- /pkgdown/favicon/web-app-manifest-192x192.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/pkgdown/favicon/web-app-manifest-192x192.png -------------------------------------------------------------------------------- /pkgdown/favicon/web-app-manifest-512x512.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kyleGrealis/froggeR/69422dc5a4958c4c200c452cce13cccfd204f381/pkgdown/favicon/web-app-manifest-512x512.png -------------------------------------------------------------------------------- /tests/testthat.R: -------------------------------------------------------------------------------- 1 | # This file is part of the standard setup for testthat. 2 | # It is recommended that you do not modify it. 3 | # 4 | # Where should you do additional test configuration? 5 | # Learn more about the roles of various files in: 6 | # * https://r-pkgs.org/testing-design.html#sec-tests-files-overview 7 | # * https://testthat.r-lib.org/articles/special-files.html 8 | 9 | library(testthat) 10 | library(froggeR) 11 | 12 | test_check("froggeR") 13 | -------------------------------------------------------------------------------- /tests/testthat/test-quarto_project.R: -------------------------------------------------------------------------------- 1 | test_that("quarto_project creates directory structure", { 2 | # Skip the test if Quarto isn't installed on the system 3 | skip_if_not(nzchar(Sys.which("quarto")), "Quarto not available") 4 | 5 | # Setup test environment: 6 | # Get system temp directory 7 | temp_dir <- tempdir() 8 | project_name <- "test_project" 9 | # Create full path 10 | proj_path <- file.path(temp_dir, project_name) 11 | 12 | # Clean up any leftovers from previous tests 13 | unlink(proj_path, recursive = TRUE, force = TRUE) 14 | # if (dir.exists(proj_path)) unlink(proj_path, recursive = TRUE) 15 | 16 | # Create the directory first to avoid file writing errors 17 | dir.create(proj_path, recursive = TRUE) 18 | 19 | # Mock (fake) the download.file function for all file writers 20 | # This prevents actual downloads during testing 21 | mockery::stub(write_ignore, "download.file", function(...) TRUE) 22 | mockery::stub(write_readme, "download.file", function(...) TRUE) 23 | mockery::stub(write_quarto, "download.file", function(...) TRUE) 24 | 25 | # Simple test: just check if directory exists 26 | expect_true(dir.exists(proj_path)) 27 | 28 | # Clean up after test 29 | unlink(proj_path, recursive = TRUE, force = TRUE) 30 | }) 31 | 32 | test_that("quarto_project handles Quarto version & errors", { 33 | # Again, skip if no Quarto 34 | skip_if_not(nzchar(Sys.which("quarto")), "Quarto not available") 35 | 36 | if (quarto::quarto_version() >= "1.4") { 37 | # Test simple error cases 38 | expect_error(quarto_project(""), "Invalid project name") # Empty string 39 | expect_error(quarto_project(" "), "Invalid project name") # Just whitespace 40 | } else { 41 | expect_error(quarto_project(""), "version") 42 | } 43 | }) 44 | -------------------------------------------------------------------------------- /tests/testthat/test-write_ignore.R: -------------------------------------------------------------------------------- 1 | test_that("write_ignore fails with bad path", { 2 | expect_error(write_ignore(path = "bad_path"), "Invalid `path`.") 3 | expect_error(write_ignore(path = " "), "Invalid `path`.") 4 | expect_error(write_ignore(path = NULL), "Invalid `path`.") 5 | }) 6 | 7 | test_that("write_ignore creates the .gitignore file correctly", { 8 | tmp_dir <- tempdir() 9 | ignore_file <- file.path(tmp_dir, ".gitignore") 10 | # Remove any prior instances 11 | unlink(ignore_file) 12 | write_ignore(tmp_dir, .initialize_proj = FALSE) 13 | expect_true(file.exists(ignore_file)) 14 | # Clean up 15 | unlink(ignore_file) 16 | expect_false(file.exists(ignore_file)) 17 | }) 18 | 19 | test_that('write_ignore creates content correctly', { 20 | tmp_dir <- tempdir() 21 | ignore_file <- file.path(tmp_dir, ".gitignore") 22 | # Remove any prior instances 23 | unlink(ignore_file) 24 | suppressMessages(write_ignore(tmp_dir, .initialize_proj = TRUE)) 25 | # Check content 26 | file_content <- readLines(ignore_file) 27 | expect_true("# History files" %in% file_content) 28 | expect_true(".Renviron" %in% file_content) 29 | expect_true("# R data" %in% file_content) 30 | expect_true("/.quarto/" %in% file_content) 31 | # Clean up 32 | unlink(ignore_file) 33 | expect_false(file.exists(ignore_file)) 34 | }) 35 | 36 | test_that('write_ignore recognizes overwrite error', { 37 | tmp_dir <- tempdir() 38 | ignore_file <- file.path(tmp_dir, ".gitignore") 39 | # Remove any prior instances 40 | unlink(ignore_file) 41 | suppressMessages(write_ignore(tmp_dir, .initialize_proj = TRUE)) 42 | # Test for error 43 | expect_error(write_ignore(tmp_dir, .initialize_proj = TRUE), 'already exists') 44 | # Clean up 45 | unlink(ignore_file) 46 | expect_false(file.exists(ignore_file)) 47 | }) 48 | -------------------------------------------------------------------------------- /tests/testthat/test-write_notes.R: -------------------------------------------------------------------------------- 1 | test_that("write_notes fails with bad path", { 2 | expect_error(write_notes(path = "bad_path"), "Invalid `path`.") 3 | expect_error(write_notes(path = " "), "Invalid `path`.") 4 | expect_error(write_notes(path = NULL), "Invalid `path`.") 5 | }) 6 | 7 | test_that("write_notes creates the notes file correctly", { 8 | tmp_dir <- tempdir() 9 | notes_file <- file.path(tmp_dir, "dated_progress_notes.md") 10 | # Remove any prior instances 11 | unlink(notes_file) 12 | write_notes(tmp_dir, .initialize_proj = FALSE) 13 | expect_true(file.exists(notes_file)) 14 | # Clean up 15 | unlink(notes_file) 16 | expect_false(file.exists(notes_file)) 17 | }) 18 | 19 | test_that('write_notes creates content correctly', { 20 | tmp_dir <- tempdir() 21 | notes_file <- file.path(tmp_dir, "dated_progress_notes.md") 22 | # Remove any prior instances 23 | unlink(notes_file) 24 | suppressMessages(write_notes(tmp_dir, .initialize_proj = TRUE)) 25 | # Check content 26 | file_content <- readLines(notes_file) 27 | expect_true("# Project updates" %in% file_content) 28 | expect_true(any(grepl(": project started$", file_content))) 29 | # Clean up 30 | unlink(notes_file) 31 | expect_false(file.exists(notes_file)) 32 | }) 33 | 34 | test_that('write_notes recognizes overwrite error', { 35 | tmp_dir <- tempdir() 36 | notes_file <- file.path(tmp_dir, "dated_progress_notes.md") 37 | # Remove any prior instances 38 | unlink(notes_file) 39 | suppressMessages(write_notes(tmp_dir, .initialize_proj = TRUE)) 40 | # Test for error 41 | expect_error(write_notes(tmp_dir, .initialize_proj = TRUE), 'already exists') 42 | # Clean up 43 | unlink(notes_file) 44 | expect_false(file.exists(notes_file)) 45 | }) 46 | -------------------------------------------------------------------------------- /tests/testthat/test-write_readme.R: -------------------------------------------------------------------------------- 1 | test_that("write_readme fails with bad path", { 2 | expect_error(write_readme(path = "bad_path"), "Invalid `path`.") 3 | expect_error(write_readme(path = " "), "Invalid `path`.") 4 | expect_error(write_readme(path = NULL), "Invalid `path`.") 5 | }) 6 | 7 | test_that("write_readme creates the README file correctly", { 8 | tmp_dir <- tempdir() 9 | readme_file <- file.path(tmp_dir, "README.md") 10 | # Remove any prior instances 11 | unlink(readme_file) 12 | write_readme(tmp_dir, .initialize_proj = FALSE) 13 | expect_true(file.exists(readme_file)) 14 | # Clean up 15 | unlink(readme_file) 16 | expect_false(file.exists(readme_file)) 17 | }) 18 | 19 | test_that('write_readme creates content correctly', { 20 | tmp_dir <- tempdir() 21 | readme_file <- file.path(tmp_dir, "README.md") 22 | # Remove any prior instances 23 | unlink(readme_file) 24 | suppressMessages(write_readme(tmp_dir, .initialize_proj = TRUE)) 25 | # Check content 26 | file_content <- readLines(readme_file) 27 | expect_true(any(grepl("Code Author", file_content))) 28 | expect_true(any(grepl("## Directories", file_content))) 29 | expect_true(any(grepl("File Descriptions", file_content))) 30 | # Clean up 31 | unlink(readme_file) 32 | expect_false(file.exists(readme_file)) 33 | }) 34 | 35 | test_that('write_readme recognizes overwrite error', { 36 | tmp_dir <- tempdir() 37 | readme_file <- file.path(tmp_dir, "README.md") 38 | # Remove any prior instances 39 | unlink(readme_file) 40 | suppressMessages(write_readme(tmp_dir, .initialize_proj = TRUE)) 41 | # Test for error 42 | expect_error(write_readme(tmp_dir, .initialize_proj = TRUE), 'already exists') 43 | # Clean up 44 | unlink(readme_file) 45 | expect_false(file.exists(readme_file)) 46 | }) 47 | -------------------------------------------------------------------------------- /tests/testthat/test-write_scss.R: -------------------------------------------------------------------------------- 1 | test_that("write_scss fails with bad path", { 2 | expect_error(write_scss(path = "bad_path"), "Invalid `path`.") 3 | expect_error(write_scss(path = " "), "Invalid `path`.") 4 | expect_error(write_scss(path = NULL), "Invalid `path`.") 5 | }) 6 | 7 | test_that("write_scss creates the SCSS file correctly", { 8 | tmp_dir <- tempdir() 9 | scss_file <- file.path(tmp_dir, "custom.scss") 10 | # Remove any prior instances 11 | unlink(scss_file) 12 | write_scss(tmp_dir, .initialize_proj = FALSE) 13 | expect_true(file.exists(scss_file)) 14 | # Clean up 15 | unlink(scss_file) 16 | expect_false(file.exists(scss_file)) 17 | }) 18 | 19 | test_that('write_scss creates content correctly', { 20 | tmp_dir <- tempdir() 21 | scss_file <- file.path(tmp_dir, "custom.scss") 22 | # Remove any prior instances 23 | unlink(scss_file) 24 | suppressMessages(write_scss(tmp_dir, .initialize_proj = TRUE)) 25 | # Check content 26 | file_content <- readLines(scss_file) 27 | expect_true("/*-- scss:defaults --*/" %in% file_content) 28 | expect_true("// $primary: #2c365e;" %in% file_content) 29 | expect_true("#title-block-header.quarto-title-block.default .quarto-title-author-orcid img {" %in% file_content) 30 | # Clean up 31 | unlink(scss_file) 32 | expect_false(file.exists(scss_file)) 33 | }) 34 | 35 | test_that('write_scss recognizes overwrite error', { 36 | tmp_dir <- tempdir() 37 | scss_file <- file.path(tmp_dir, "custom.scss") 38 | # Remove any prior instances 39 | unlink(scss_file) 40 | suppressMessages(write_scss(tmp_dir, .initialize_proj = TRUE)) 41 | # Test for error 42 | expect_error(write_scss(tmp_dir, .initialize_proj = TRUE), 'already exists') 43 | # Clean up 44 | unlink(scss_file) 45 | expect_false(file.exists(scss_file)) 46 | }) 47 | -------------------------------------------------------------------------------- /tests/testthat/test-write_variables.R: -------------------------------------------------------------------------------- 1 | test_that("write_variables fails with bad path", { 2 | expect_error(write_variables(path = 'bad_path'), 'Invalid `path`.') 3 | expect_error(write_variables(path = ' '), 'Invalid `path`.') 4 | expect_error(write_variables(path = NULL), 'Invalid `path`.') 5 | }) 6 | 7 | test_that("write_variables creates _variables.yml correctly", { 8 | tmp_dir <- tempdir() 9 | variables_file <- file.path(tmp_dir, "_variables.yml") 10 | # Remove any prior instances 11 | unlink(variables_file) 12 | write_variables(tmp_dir, .initialize_proj = FALSE) 13 | expect_true(file.exists(variables_file)) 14 | # Clean up 15 | unlink(variables_file) 16 | expect_false(file.exists(variables_file)) 17 | }) 18 | 19 | test_that("write_variables creates content correctly", { 20 | tmp_dir <- tempdir() 21 | variables_file <- file.path(tmp_dir, "_variables.yml") 22 | # Remove any prior instances 23 | unlink(variables_file) 24 | suppressMessages(write_variables(tmp_dir, .initialize_proj = TRUE)) 25 | # Check content 26 | file_content <- readLines(variables_file) 27 | expect_true(any(grepl('^name: ', file_content))) 28 | expect_true(any(grepl('^email: ', file_content))) 29 | expect_true(any(grepl('^orcid: ', file_content))) 30 | expect_true(any(grepl('^url: ', file_content))) 31 | # Clean up 32 | unlink(variables_file) 33 | expect_false(file.exists(variables_file)) 34 | }) 35 | 36 | test_that('write_variables recognizes overwrite error', { 37 | tmp_dir <- tempdir() 38 | variables_file <- file.path(tmp_dir, "_variables.yml") 39 | # Remove any prior instances 40 | unlink(variables_file) 41 | suppressMessages(write_variables(tmp_dir, .initialize_proj = TRUE)) 42 | # Test for error 43 | expect_error(write_variables(tmp_dir, .initialize_proj = TRUE), 'already exists') 44 | # Clean up 45 | unlink(variables_file) 46 | expect_false(file.exists(variables_file)) 47 | }) 48 | -------------------------------------------------------------------------------- /vignettes/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | *.R 3 | 4 | /.quarto/ 5 | -------------------------------------------------------------------------------- /vignettes/customizing-quarto.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Customizing Quarto with froggeR" 3 | output: rmarkdown::html_vignette 4 | vignette: > 5 | %\VignetteIndexEntry{Customizing Quarto with froggeR} 6 | %\VignetteEngine{knitr::rmarkdown} 7 | %\VignetteEncoding{UTF-8} 8 | --- 9 | 10 | ```{r, include = FALSE} 11 | knitr::opts_chunk$set( 12 | collapse = TRUE, 13 | comment = "#>" 14 | ) 15 | ``` 16 | 17 | ## Introduction 18 | 19 | One of froggeR's core strengths is its ability to maintain consistent settings and styling across multiple projects. This vignette demonstrates how to set up and customize your Quarto documents using froggeR's SCSS document. 20 | 21 | ---- 22 | 23 | ## Using Custom Variables in Quarto Documents 24 | 25 | froggeR allows you to use variables from your `_variables.yml` file directly in your `_quarto.yml` or Quarto documents: 26 | 27 | ```yaml 28 | --- 29 | title: "My Document" 30 | author: "{{< var author >}}" 31 | date: "{{< var date >}}" 32 | --- 33 | ``` 34 | 35 | This ensures consistency across all your project documents and makes updates easier to manage. 36 | 37 | ---- 38 | 39 | ## Document Styling with SCSS 40 | 41 | ### Understanding SCSS Structure 42 | 43 | The [`write_scss()`](https://www.kyleGrealis.com/froggeR/reference/write_scss.html) function creates a template with three main sections: 44 | 45 | 1. **Defaults** (`/*-- scss:defaults --*/`) 46 | * Basic styling variables 47 | * Color schemes 48 | * Font settings 49 | 50 | 2. **Mixins** (`/*-- scss:mixins --*/`) 51 | * Reusable style patterns 52 | * Custom style functions 53 | 54 | 3. **Rules** (`/*-- scss:rules --*/`) 55 | * Specific element styling 56 | * Custom classes 57 | * Layout adjustments 58 | 59 | ### Working with Comments 60 | 61 | The SCSS template uses `//` for commented styles. These act like a menu of styling options: 62 | 63 | ```scss 64 | /*-- scss:defaults --*/ 65 | // $primary: #2c365e; // Main theme color 66 | // $body-bg: #fefefe; // Background color 67 | // $link-color: $primary; // Inherit from primary 68 | ``` 69 | 70 | To activate any style: 71 | 72 | 1. Remove the `//` at the start of the line 73 | 2. Save the file 74 | 3. Re-render your document 75 | 76 | ### Working with Multiple SCSS Files 77 | 78 | To multiple or a organization-specific SCSS file in your Quarto document, update the YAML header. Be advised that modifying the *document*-level YAML (i.e., the YAML for the .qmd file) will override any options set in `_quarto.yml` & `_variables.yml`. 79 | 80 | ```yaml 81 | --- 82 | title: "My Document" 83 | format: 84 | html: 85 | theme: 86 | - default 87 | - custom.scss # Added during project 88 | - your-other.scss # The new one you're adding 89 | --- 90 | ``` 91 | 92 | > **Note**: Order matters! Any style(s) set in `custom.scss` override Quarto's defaults, and `your-other.scss` overrides the previous two. If your document isn't rendering as you believe it should, check the files. If you have a border style set in `custom.scss` but the output file isn't correct, there's a good possibility that there's something set in `your-other.scss` causing conflicts. Resolve the issue and re-render. :) 93 | 94 | ### Basic Customization Examples 95 | 96 | #### Link Color 97 | 98 | Here's an example of changing the default link color from the assigned `$primary` color (blue) to dark green. 99 | 100 | ```{r, echo=FALSE, fig.align='center', fig.cap='Link color styling - Before', out.width='70%'} 101 | knitr::include_graphics("../man/figures/link_color_before.png") 102 | ``` 103 | 104 | ```scss 105 | /*-- scss:defaults --*/ 106 | // These lines are inactive (commented out): 107 | // $link-color: $primary; 108 | ``` 109 | 110 | Remove the `//` to activate and change `$primary` to `#1e6909`: 111 | 112 | ```scss 113 | $link-color: #1e69090; 114 | ``` 115 | 116 | ```{r, echo=FALSE, fig.align='center', fig.cap='Link color styling - After', out.width='70%'} 117 | knitr::include_graphics("../man/figures/link_color_after.png") 118 | ``` 119 | 120 | #### Theme Colors 121 | 122 | The `custom.scss` template includes common color variables: 123 | 124 | ```scss 125 | /*-- scss:defaults --*/ 126 | $primary: #1a936f; // Forest green 127 | $body-bg: #f8f9fa; // Light gray 128 | ``` 129 | 130 | ### Advanced Customization 131 | 132 | Combine multiple elements for sophisticated styling: 133 | 134 | ```scss 135 | /*-- scss:defaults --*/ 136 | // First, set your variables 137 | $primary: #2c365e; 138 | $font-family-monospace: "Fira Code", monospace; 139 | 140 | /*-- scss:rules --*/ 141 | // Then create custom rules 142 | .title-block { 143 | margin-bottom: 2rem; 144 | border-bottom: 3px solid $primary; 145 | 146 | h1 { 147 | color: darken($primary, 10%); 148 | font-weight: 600; 149 | } 150 | } 151 | 152 | // Style code elements 153 | code { 154 | color: lighten($primary, 10%); 155 | padding: 0.2em 0.4em; 156 | border-radius: 3px; 157 | } 158 | ``` 159 | 160 | ---- 161 | 162 | ## Quick Styling Recipes 163 | 164 | ### Modern Document Headers 165 | 166 | ```scss 167 | /*-- scss:rules --*/ 168 | .title-block { 169 | background: linear-gradient(to right, $primary, lighten($primary, 20%)); 170 | padding: 2rem; 171 | margin-bottom: 3rem; 172 | color: white; 173 | border-radius: 5px; 174 | } 175 | ``` 176 | 177 | ### Enhanced Code Blocks 178 | 179 | ```scss 180 | /*-- scss:defaults --*/ 181 | $code-block-bg: #f8f9fa; 182 | $font-family-monospace: "Fira Code", monospace; 183 | 184 | /*-- scss:rules --*/ 185 | pre { 186 | border-radius: 4px; 187 | box-shadow: 0 2px 4px rgba(0,0,0,0.1); 188 | margin: 1.5em 0; 189 | } 190 | ``` 191 | 192 | ### Professional Links 193 | 194 | ```scss 195 | /*-- scss:rules --*/ 196 | a:not(.nav-link) { 197 | border-bottom: 1px dotted $primary; 198 | text-decoration: none; 199 | transition: all 0.2s ease; 200 | 201 | &:hover { 202 | border-bottom: 1px solid $primary; 203 | background-color: rgba($primary, 0.1); 204 | } 205 | } 206 | ``` 207 | 208 | ---- 209 | 210 | ## Common Issues and Solutions 211 | 212 | ### Settings Issues 213 | 214 | 1. **Variables Not Updating** 215 | * Restart R session after `config.yml` changes 216 | * Check `_variables.yml` exists in project 217 | * Verify YAML structure in documents 218 | 219 | 2. **Multiple Projects** 220 | * Settings apply to new projects only 221 | * Existing projects keep their settings 222 | * Update `_variables.yml` manually if needed 223 | 224 | ---- 225 | 226 | ## Additional Resources 227 | 228 | For more advanced SCSS customization options, visit: 229 | 230 | * [Quarto HTML Themes](https://quarto.org/docs/output-formats/html-themes.html#customizing-themes){target="_blank"} 231 | * [More Theme Options](https://quarto.org/docs/output-formats/html-themes-more.html){target="_blank"} 232 | * [Bootstrap Variables](https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss){target="_blank"} 233 | 234 | ---- 235 | 236 | ## Summary 237 | 238 | froggeR streamlines document customization: 239 | 240 | 1. Set up once with `settings()` 241 | 2. Style with `write_scss()` 242 | 3. Reuse across all your projects 243 | 4. Update easily when needed 244 | 245 | Happy styling! 🐸 246 | 247 | ---- 248 | 249 | *Consistent, professional documents with minimal effort* -------------------------------------------------------------------------------- /vignettes/hopping-into-quarto.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Get Hopping with froggeR" 3 | output: rmarkdown::html_vignette 4 | vignette: > 5 | %\VignetteIndexEntry{Get Hopping with froggeR} 6 | %\VignetteEngine{knitr::rmarkdown} 7 | %\VignetteEncoding{UTF-8} 8 | --- 9 | 10 | ```{r, include = FALSE} 11 | knitr::opts_chunk$set( 12 | collapse = TRUE, 13 | comment = "#>" 14 | ) 15 | ``` 16 | 17 | ## Introduction 18 | 19 | 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. 20 | 21 | ```r 22 | # Install from GitHub 23 | install.packages("kyleGrealis/froggeR") 24 | ``` 25 | 26 | ---- 27 | 28 | ## Core Features 29 | 30 | Project setup often involves repetitive tasks that can impede your analysis workflow. froggeR addresses this by providing: 31 | 32 | * Automated project initialization with [`quarto_project()`](https://www.kyleGrealis.com/froggeR/reference/quarto_project.html) 33 | * Reusable project configurations through [`settings()`](https://www.kyleGrealis.com/froggeR/reference/froggeR_settings.html) 34 | * Replicate Quarto project brand styling with [`write_brand()`](https://www.kyleGrealis.com/froggeR/reference/write_brand.html) and [`save_brand()`](https://www.kyleGrealis.com/froggeR/reference/save_brand.html) 35 | * Configurable document templates via [`write_quarto()`](https://www.kyleGrealis.com/froggeR/reference/write_quarto.html) 36 | * Consistent styling with [`write_scss()`](https://www.kyleGrealis.com/froggeR/reference/write_scss.html) 37 | * Enhanced version control setup 38 | * Easily add project documentation templates to any existing project, even those not initialized by froggeR. 39 | 40 | ---- 41 | 42 | ## SPOILER ALERT!! 43 | 44 | All of the components listed below are available when you begin your Quarto projects with: 45 | 46 | ```r 47 | froggeR::quarto_project() 48 | ``` 49 | 50 | 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! 51 | 52 | ---- 53 | 54 | ## Quick Start Guide 55 | 56 | Create a new Quarto project with a single command: 57 | 58 | ```r 59 | >> froggeR::quarto_project(name = "frogs") 60 | This will create a new Quarto default project as a folder named frogs in 61 | /home/kyle. 62 | Do you want to proceed (Y/n)? 63 | Y 64 | ✔ Created Quarto project directory: frogs 65 | ✔ Created _quarto.yml 66 | ℹ Copying existing froggeR settings... 67 | ✔ Created _variables.yml 68 | ℹ Copying existing froggeR brand settings... 69 | ✔ Created _brand.yml 70 | ✔ Copying existing froggeR logos. 71 | ✔ Created custom.scss 72 | ✔ Created .gitignore 73 | ✔ Created README.md 74 | ✔ Created dated_progress_notes.md 75 | ✔ Created frogs.qmd with examples 76 | ✔ Created references.bib 77 | ✔ froggeR project setup complete. Opening in new session... 78 | ``` 79 | 80 | This command initializes a complete project structure with all necessary components: 81 | 82 | ### Project Components 83 | 84 | 1. **Quarto Document** 85 | * Pre-configured YAML header 86 | * Examples for adding brand logo, HTML in-document cross-references, and HTML links 87 | * Example for adding citations and references 88 | 89 | 2. **Style Sheet** 90 | * Modern design elements 91 | * Customizable components 92 | * Clear documentation 93 | 94 | 3. **Project Configuration** 95 | * `_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. 96 | * `_variables.yml` for consistent user metadata 97 | * `_brand.yml` for consistent project branding metadata 98 | * `.gitignore` for secure version control 99 | 100 | 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`). 101 | 102 | 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. 103 | 104 | 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! 105 | 106 | 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! 107 | 108 | > **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. 109 | 110 | See `vignette("customizing-quarto", package = "froggeR")` for more detailed configuration options. 111 | 112 | ---- 113 | 114 | ## Customization 115 | 116 | ### Document Settings 117 | 118 | > You may choose to setup your froggeR metadata before creating your first project. 119 | 120 | Manage your document settings with the interactive configuration tool (see `?froggeR::settings` for all options): 121 | 122 | ```r 123 | # Check, display, or update your settings 124 | >> froggeR::settings() 125 | 126 | froggeR settings options: 127 | 128 | 1: Check for config files 129 | 2: Display current settings 130 | 3: Show how to update settings 131 | 4: Show how to reuse settings across projects 132 | 5: More information about settings 133 | 134 | Selection: 135 | 1 136 | 137 | ℹ Run froggeR::write_variables() to create project-level settings. 138 | ``` 139 | 140 | To create and open the `_variables.yml` file for immediate customization, run: 141 | 142 | ```r 143 | # Create project-level metadata 144 | froggeR::write_variables() 145 | ``` 146 | 147 | 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. 148 | 149 | ```r 150 | # You do not need to use quotes around values. 151 | # You may edit any value or leave it blank. 152 | name: 153 | email: 154 | orcid: 155 | url: #https://example.com 156 | affiliations: 157 | ``` 158 | 159 | 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 reinforces froggeR's goal to increase your effeciency now and for future projects. 160 | 161 | These settings flow through your projects in this order: 162 | 163 | 1. `config.yml` stores your permanent settings (exact location depends on your OS) 164 | 2. froggeR reads these when creating new projects 165 | 3. Settings populate `_variables.yml` in your project 166 | 4. Quarto documents use these variables automatically 167 | 168 |
169 |
170 | How froggeR manages settings across projects (config.yml) 171 |
How froggeR manages settings across projects (config.yml)
172 |
173 |
174 | 175 | > **Note:** While you can update these settings at any time, most users find they only need to set them once or very infrequently. 176 | 177 | **Congratulations!** You've just made your next Quarto project with froggeR even easier! But how? Well, let's have a little fun: delete the `_variables.yml` in your **local** project you just created. Don't worry... we'll make it reappear, but this time you will not need to reinput the value fields. Once again, run `froggeR::write_variables()` and voila! You should see your saved config file that matches the one you just deleted... and it's already filled in! 178 | 179 | This is froggeR's main benefit: making Quarto documents and projects easier the next time too. Later we'll see how `froggeR::quarto_project()` will pull this information the next time while setting up the entire project structure. You can skip ahead to the vignette, if you like. 180 | 181 | 182 | ### Create a Quarto document with examples 183 | 184 | Quickly create a Quarto document that includes examples for adding your brand logo, section and other within-document cross-references, hyperlinks, and references with `froggeR::write_quarto(example = TRUE)`. This opens a new file with the default name of "Untitled-1.qmd". 185 | 186 | 187 | The template will open: 188 | 189 |
190 |
191 | Quarto template with examples 192 |
Quarto template with examples
193 |
194 |
195 | 196 | 197 | ### Visual Styling 198 | 199 | Customize your document appearance with SCSS: 200 | 201 | ```r 202 | froggeR::write_scss() 203 | ``` 204 | 205 | This creates a `custom.scss` file with commented-out examples. Uncomment and modify these to customize your document's appearance. For more information on Quarto styling, refer to: 206 | 207 | - [Quarto HTML Themes](https://quarto.org/docs/output-formats/html-themes.html) 208 | - [Customizing Quarto Themes](https://quarto.org/docs/output-formats/html-themes.html#customizing-themes) 209 | 210 | ---- 211 | 212 | ## Advanced Usage 213 | 214 | ### Project Documentation 215 | 216 | Generate comprehensive project documentation: 217 | 218 | ```{r, eval=FALSE} 219 | froggeR::write_readme() 220 | froggeR::write_notes() 221 | ``` 222 | 223 | The README template was designed for academia in mind (notice the references to "PI", or principle investigator, within the file), but is adaptable to meet your needs. There are sections for explaining how to use your project, what the directories and files contain, and created so you can focus more on creating content. 224 | 225 | We've included a `dated_progress_notes.md` file. A study with sample size *N=1* has demonstrated that this has really helped ~~me~~ the study participant refresh memory after a few weeks away from a project. 226 | 227 | ---- 228 | 229 | ## Best Practices 230 | 231 | For optimal results with froggeR: 232 | 233 | 1. **Use metadata in your projects** 234 | * Follow guide to save your metadata in the configuration file 235 | * Initialize projects with `quarto_project()` or `write_quarto()` 236 | * Review Quarto documentation to really open up your projects 237 | 238 | 1. **Project Organization** 239 | * Use consistent naming conventions 240 | * Maintain clear directory structure 241 | * Document project changes 242 | 243 | 1. **Version Control** 244 | * Review `.gitignore` settings 245 | * Update progress notes regularly 246 | * Maintain README documentation 247 | 248 | 1. **Styling** 249 | * Test SCSS changes before implementation 250 | * Document custom styling decisions 251 | * Use variables for consistency 252 | 253 | ---- 254 | 255 | ## Troubleshooting and FAQs 256 | 257 | ### Common Issues 258 | 259 | 1. **Q: My YAML isn't rendering correctly in the Quarto document.** 260 | 261 | A: Ensure that your `_variables.yml` file is properly formatted. Check for any extra spaces or incorrect indentation. 262 | 263 | 2. **Q: The SCSS styles aren't applying to my document.** 264 | 265 | A: Make sure the SCSS file is properly linked in your YAML header. Remember, the order of the styles sheets matters. During the initialization of `froggeR::write_quarto(custom_yaml = TRUE)`, the `custom.scss` will override anything set in the `default` styling. The same applies if another SCSS sheet is added -- it will override all SCSS files listed above it. Check the console for any error messages during rendering. 266 | 267 | 3. **Q: I'm getting an error when trying to create a new project.** 268 | 269 | A: Ensure you have the latest version of froggeR and Quarto installed. Also, check if you have write permissions in the target directory. 270 | 271 | ### Tips for Smoother Projects 272 | 273 | - Always review the generated files after project creation to ensure everything is set up as expected. 274 | - When customizing SCSS, make small changes and render frequently to see the effects. 275 | - Keep your froggeR settings up-to-date, especially when working across multiple projects. 276 | 277 | For more specific issues, consult the documentation or reach out through the GitHub issue tracker. 278 | 279 | ---- 280 | 281 | ## Getting Help 282 | 283 | Need assistance? Several resources are available: 284 | 285 | * Function documentation (e.g., `?write_quarto`) 286 | * [GitHub repository](https://github.com/kyleGrealis/froggeR) 287 | * Issue tracker for bug reports and feature requests 288 | * See `vignette("customizing-quarto", package = "froggeR")` for styling details 289 | 290 | ---- 291 | 292 | ## Future Developments 293 | 294 | froggeR is continuously evolving to meet the needs of the R and Quarto community. Some exciting features on our roadmap include: 295 | 296 | - **Quarto Dashboard Integration**: Streamlined creation and management of interactive Quarto dashboards. 297 | - **Enhanced Version Control Integration**: More robust Git integration features. 298 | - **Expanded Customization Options**: Additional templates and styling options for diverse project needs. 299 | - **Collaborative Tools**: Features to enhance team workflows and project sharing. 300 | 301 | Stay tuned to our GitHub repository for updates and new releases. We welcome feature requests and feedback from our user community to help shape the future of froggeR! 302 | 303 | ---- 304 | 305 | ## Summary 306 | 307 | froggeR provides a streamlined approach to Quarto project management, offering: 308 | 309 | * Efficient project initialization 310 | * Consistent document styling 311 | * Secure version control 312 | * Comprehensive documentation 313 | 314 | Happy analyzing! 🐸 315 | 316 | --- 317 | 318 | *Elevating your Quarto workflow with automated excellence* -------------------------------------------------------------------------------- /vignettes/quarto-workflow.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Quarto Workflow with froggeR" 3 | output: rmarkdown::html_vignette 4 | vignette: > 5 | %\VignetteIndexEntry{Quarto Workflow with froggeR} 6 | %\VignetteEngine{knitr::rmarkdown} 7 | %\VignetteEncoding{UTF-8} 8 | --- 9 | 10 | ```{r, include = FALSE} 11 | knitr::opts_chunk$set( 12 | collapse = TRUE, 13 | comment = "#>" 14 | ) 15 | ``` 16 | 17 | ## Introduction 18 | 19 | froggeR streamlines your Quarto workflow by providing two powerful functions: [`quarto_project()`](https://www.kyleGrealis.com/froggeR/reference/quarto_project.html) for complete project initialization and [`write_quarto()`](https://www.kyleGrealis.com/froggeR/reference/write_quarto.html) for individual document creation. This vignette demonstrates how to use these functions effectively and how they work together. 20 | 21 | ---- 22 | 23 | ## Project Creation 24 | 25 | ### Complete Project Setup 26 | 27 | The quickest way to start a new Quarto project: 28 | 29 | ```r 30 | >> froggeR::quarto_project(name = "frogs") 31 | This will create a new Quarto default project as a folder named frogs in 32 | /home/kyle. 33 | Do you want to proceed (Y/n)? 34 | Y 35 | ✔ Created Quarto project directory: frogs 36 | ✔ Created _quarto.yml 37 | ℹ Copying existing froggeR settings... 38 | ✔ Created _variables.yml 39 | ℹ Copying existing froggeR brand settings... 40 | ✔ Created _brand.yml 41 | ✔ Copying existing froggeR logos. 42 | ✔ Created custom.scss 43 | ✔ Created .gitignore 44 | ✔ Created README.md 45 | ✔ Created dated_progress_notes.md 46 | ✔ Created frogs.qmd with examples 47 | ✔ Created references.bib 48 | ✔ froggeR project setup complete. Opening in new session... 49 | ``` 50 | 51 | This single command creates a complete project structure: 52 | 53 | | Component | Description | 54 | |-----------|-------------| 55 | | `frogs/` | Main project directory | 56 | | `frogs.qmd` | Main Quarto document | 57 | | `_quarto.yml` | Reusable project settings | 58 | | `_variables.yml` | Reusable document settings | 59 | | `_brand.yml` | Reusable brand style settings | 60 | | `custom.scss` | Style sheet template | 61 | | `dated_progress_notes.md` | Project documentation | 62 | | `README.md` | Project documentation | 63 | | `.gitignore` | Enhanced security settings | 64 | | `references.bib` | Example citation template | 65 | 66 | ### Understanding Project Components 67 | 68 | Each component serves a specific purpose: 69 | 70 | 1. **Quarto Document** (`_quarto.yml`) 71 | * Pre-configured YAML to import `_variables.yml` 72 | * Links to styling files 73 | * Familiar format toggles 74 | 75 | 76 | 2. **Project Settings** (`_variables.yml`) 77 | 78 | ```yaml 79 | author: Your Name 80 | email: your.email@example.com 81 | affiliations: Your Institution 82 | ``` 83 | 84 |
85 |
86 | variables dot yml 87 |
Project metadata
88 |
89 |
90 | 91 | 92 | 3. **Brand Settings** (*new* for froggeR v0.5.0; `_brand.yml`) 93 | * Preconfigured branding file 94 | * Examples for adding logo, color, & typography 95 | * Save your personal or team art in the `logos/` directory 96 | * **Add a consistent style** across your Quarto documents 97 | 98 | 99 | 4. **Style Sheet** (`custom.scss`) 100 | * Professional defaults 101 | * Customizable elements 102 | * Clear documentation 103 | 104 | ---- 105 | 106 | ## Individual Document Creation 107 | 108 | 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. 109 | 110 | ---- 111 | 112 | ## Rendered Output 113 | 114 | ```{r, echo=FALSE, fig.align='center', fig.cap='Example output of custom_yaml document', out.width='85%'} 115 | knitr::include_graphics("../man/figures/custom-yaml-rendered.png") 116 | ``` 117 | 118 | > **Note**: This example uses a froggeR version pre-0.5.0 though the main heading will render the same... you get the point ;) 119 | 120 | ---- 121 | 122 | ## Workflow Integration 123 | 124 | ### Project-Level Workflow 125 | 126 | Best practices for project organization: 127 | 128 | 1. **Initial Setup** 129 | 130 | ```{r, eval=FALSE} 131 | # Create new project 132 | froggeR::quarto_project(name = "frogs") 133 | ``` 134 | 135 | Recommended project structure: 136 | 137 | | Directory/File | Purpose | Contents | 138 | |----------------|---------|-----------| 139 | | `data/` | Raw data storage | Input files, datasets | 140 | | `logos/` | Brand logos | Storing Quarto brand art | 141 | | `output/` | Analysis results | Figures, tables, exports | 142 | | `R/` | Custom functions | R scripts, utilities | 143 | | `docs/` | Documentation | Additional guides, notes | 144 | | `*.qmd`\** | Analysis documents | Main content and code | 145 | \** *This is provided from `froggeR::quarto_project()`. All others need to be created.* 146 | 147 | 2. **Additional Documents** 148 | 149 | ```{r, eval=FALSE} 150 | # Add analysis documents 151 | froggeR::write_quarto( 152 | filename = "data_prep" 153 | ) 154 | 155 | froggeR::write_quarto( 156 | filename = "analysis" 157 | ) 158 | ``` 159 | 160 | 3. **Project Structure** 161 | 162 | ``` 163 | frogs/ 164 | ├── frogs.qmd 165 | ├── data_prep.qmd 166 | ├── analysis.qmd 167 | ├── _brand.yml 168 | ├── _quarto.yml 169 | ├── _variables.yml 170 | ├── custom.scss 171 | ├── dated_progress_notes.md 172 | ├── references.bib 173 | └── README.md 174 | ``` 175 | 176 | ### Document Management 177 | 178 | Tips for effective document organization: 179 | 180 | 1. **Consistent Naming** 181 | * Use descriptive filenames 182 | * Follow a naming convention 183 | * Consider document order 184 | 185 | 2. **Settings Management** 186 | * Keep `_variables.yml` updated 187 | * Maintain consistent styling 188 | * Document customizations 189 | 190 | 3. **Version Control** 191 | * Commit regularly 192 | * Update README 193 | * Track progress 194 | 195 | Common `.gitignore` patterns: 196 | 197 | | Pattern | Excludes | Why | 198 | |---------|----------|-----| 199 | | `*.rds` | R data files | Data security | 200 | | `.Rhistory` | R history files | Session cleanup | 201 | | `output/` | Generated files | Avoid tracking outputs | 202 | | `*.html` | Rendered documents | Focus on source files | 203 | 204 | ---- 205 | 206 | ## Common Customizations 207 | 208 | ### Project Modifications 209 | 210 | Customize your project structure: 211 | 212 | ```{r, eval=FALSE} 213 | froggeR::quarto_project(name = "my_project") 214 | ``` 215 | 216 | Then add specialized documents: 217 | 218 | ```{r, eval=FALSE} 219 | # Data preparation 220 | froggeR::write_quarto(filename = "01_data_prep") 221 | 222 | # Analysis 223 | froggeR::write_quarto(filename = "02_analysis") 224 | 225 | # Results 226 | froggeR::write_quarto(filename = "03_results") 227 | ``` 228 | 229 | > **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. 230 | 231 | ### Document Customization 232 | 233 | 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`. 234 | 235 | 1. **YAML Additions** 236 | 237 | ```yaml 238 | --- 239 | title: "Analysis Results" 240 | author: "{{< var author >}}" 241 | date: last-modified 242 | format: 243 | html: 244 | code-fold: true 245 | toc: true 246 | --- 247 | ``` 248 | 249 | 2. **Style Variations** 250 | * Uncomment chosen lines in the `custom.scss` file (provided) 251 | * Modify existing styles 252 | * Add document-specific rules 253 | 254 | ---- 255 | 256 | ## Troubleshooting 257 | 258 | Common issues and solutions: 259 | 260 | 1. **Project Creation Issues** 261 | * Verify directory permissions 262 | * Check for existing projects 263 | * Ensure valid project name 264 | 265 | 2. **Document Problems** 266 | * Confirm `_variables.yml` & `_quarto.yml` exist 267 | * Check YAML syntax 268 | * Verify file locations 269 | 270 | 3. **Style Integration** 271 | * Review SCSS references 272 | * Check file paths 273 | * Validate YAML structure 274 | 275 | ---- 276 | 277 | ## Additional Resources 278 | 279 | For more information on: 280 | 281 | * Quarto documents: `vignette("customizing-quarto", package = "froggeR")` 282 | * Project styling: See `?write_scss` 283 | * Settings management: See `?settings` 284 | 285 | ---- 286 | 287 | ## Summary 288 | 289 | froggeR's project workflow provides: 290 | 291 | * Efficient project initialization 292 | * Consistent document creation 293 | * Integrated styling 294 | * Automated setup 295 | * Professional templates 296 | 297 | Happy documenting! 🐸 298 | 299 | --- 300 | 301 | *Streamlined Quarto workflows with automated excellence* --------------------------------------------------------------------------------