├── .github ├── .gitignore ├── workflows │ ├── pkgdown.yaml │ └── R-CMD-check.yaml ├── CODE_OF_CONDUCT.md └── CONTRIBUTING.md ├── vignettes ├── .gitignore ├── yaml-fieldguide.Rmd └── yaml-overview.Rmd ├── LICENSE ├── man-roxygen ├── describe_yml_output.R ├── describe_dots_param.R └── describe_yml_param.R ├── tests ├── testthat.R ├── testthat │ ├── helper-utils.R │ ├── _snaps │ │ ├── basic_yaml_results.md │ │ └── markdownr.md │ ├── test-markdownr.R │ ├── test-helpers_work.R │ ├── test-bookdown_yaml.R │ ├── test-blogdown_yaml.R │ ├── test-rmarkdown_functions.R │ └── test-basic_yaml_results.R └── spelling.R ├── man ├── figures │ └── README-pressure-1.png ├── pipe.Rd ├── is_yml.Rd ├── last_yml.Rd ├── yml_load.Rd ├── yml_handlers.Rd ├── as_yml.Rd ├── yml_verbatim.Rd ├── yml_blank.Rd ├── yml_code.Rd ├── includes2.Rd ├── blogdown_template.Rd ├── code_chunk.Rd ├── pkgdown_template.Rd ├── pandoc_template_types.Rd ├── asis_yaml_output.Rd ├── has_field.Rd ├── draw_yml_tree.Rd ├── bib2yml.Rd ├── yml_resource_files.Rd ├── yml_clean.Rd ├── yml_toc.Rd ├── yml_runtime.Rd ├── use_yml_defaults.Rd ├── yml_output.Rd ├── yml_vignette.Rd ├── yml.Rd ├── read_json.Rd ├── yml_replace.Rd ├── yml_pagedown_opts.Rd ├── gitbook_config.Rd ├── yml_citations.Rd ├── pagedown_business_card_template.Rd ├── use_file_yml.Rd ├── use_yml.Rd ├── yml_rsconnect_email.Rd ├── yml_reference.Rd ├── yml_site_opts.Rd ├── yml_rticles_opts.Rd ├── yml_bookdown_opts.Rd ├── yml_author.Rd └── yml_blogdown_opts.Rd ├── .gitignore ├── inst ├── rstudio │ └── addins.dcf ├── WORDLIST └── addin │ └── new_yaml │ ├── server.R │ └── global.R ├── codecov.yml ├── R ├── utils-pipe.R ├── addins.R ├── read_yaml.R ├── yml_replace.R ├── markdownr.R ├── use_pandoc.R ├── yml_output.R ├── utils.R ├── draw_tree.R ├── yml_rsconnect.R ├── yml_helpers.R ├── convert_metadata.R ├── yml_rticles.R └── yml_pagedown.R ├── cran-comments.md ├── .Rbuildignore ├── ymlthis.Rproj ├── LICENSE.md ├── NEWS.md ├── DESCRIPTION ├── _pkgdown.yml ├── README.Rmd ├── README.md └── NAMESPACE /.github/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | -------------------------------------------------------------------------------- /vignettes/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | *.R 3 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | YEAR: 2019 2 | COPYRIGHT HOLDER: Malcolm Barrett 3 | -------------------------------------------------------------------------------- /man-roxygen/describe_yml_output.R: -------------------------------------------------------------------------------- 1 | #' @return a `yml` object 2 | #' 3 | #' @md 4 | -------------------------------------------------------------------------------- /tests/testthat.R: -------------------------------------------------------------------------------- 1 | library(testthat) 2 | library(ymlthis) 3 | 4 | test_check("ymlthis") 5 | -------------------------------------------------------------------------------- /man/figures/README-pressure-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-lib/ymlthis/HEAD/man/figures/README-pressure-1.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | .Ruserdata 5 | docs 6 | inst/doc 7 | Untitled.Rmd 8 | Untitled.html 9 | rhub.R 10 | revdep 11 | -------------------------------------------------------------------------------- /man-roxygen/describe_dots_param.R: -------------------------------------------------------------------------------- 1 | #' @param ... additional named R objects, such as characters or lists, to 2 | #' transform into YAML 3 | #' 4 | #' @md 5 | -------------------------------------------------------------------------------- /tests/testthat/helper-utils.R: -------------------------------------------------------------------------------- 1 | library(ymlthis) 2 | stringify_yaml <- function(x) { 3 | x %>% 4 | ymlthis:::capture_yml() %>% 5 | paste(collapse = "\n") 6 | } 7 | -------------------------------------------------------------------------------- /man-roxygen/describe_yml_param.R: -------------------------------------------------------------------------------- 1 | #' @param .yml a `yml` object created by `yml()`, `as_yml()`, or returned by 2 | #' a `yml_*()` function 3 | #' 4 | #' @family yml 5 | #' 6 | #' @md 7 | -------------------------------------------------------------------------------- /tests/spelling.R: -------------------------------------------------------------------------------- 1 | if(requireNamespace('spelling', quietly = TRUE)) 2 | spelling::spell_check_test(vignettes = TRUE, error = TRUE, 3 | skip_on_cran = TRUE) 4 | -------------------------------------------------------------------------------- /inst/rstudio/addins.dcf: -------------------------------------------------------------------------------- 1 | Name: Write New R Markdown or YAML File 2 | Description: Write YAML and send it to a new R Markdown file, YAML file, or copy it to your clipboard 3 | Binding: launch_yaml_addin 4 | Interactive: true 5 | 6 | -------------------------------------------------------------------------------- /codecov.yml: -------------------------------------------------------------------------------- 1 | comment: false 2 | 3 | coverage: 4 | status: 5 | project: 6 | default: 7 | target: auto 8 | threshold: 1% 9 | patch: 10 | default: 11 | target: auto 12 | threshold: 1% 13 | -------------------------------------------------------------------------------- /R/utils-pipe.R: -------------------------------------------------------------------------------- 1 | #' Pipe operator 2 | #' 3 | #' See \code{magrittr::\link[magrittr]{\%>\%}} for details. 4 | #' 5 | #' @name %>% 6 | #' @rdname pipe 7 | #' @keywords internal 8 | #' @export 9 | #' @importFrom magrittr %>% 10 | #' @usage lhs \%>\% rhs 11 | NULL 12 | -------------------------------------------------------------------------------- /man/pipe.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utils-pipe.R 3 | \name{\%>\%} 4 | \alias{\%>\%} 5 | \title{Pipe operator} 6 | \usage{ 7 | lhs \%>\% rhs 8 | } 9 | \description{ 10 | See \code{magrittr::\link[magrittr]{\%>\%}} for details. 11 | } 12 | \keyword{internal} 13 | -------------------------------------------------------------------------------- /man/is_yml.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml.R 3 | \name{is_yml} 4 | \alias{is_yml} 5 | \title{Is object a yml object?} 6 | \usage{ 7 | is_yml(x) 8 | } 9 | \arguments{ 10 | \item{x}{An object to test} 11 | } 12 | \value{ 13 | A logical vector 14 | } 15 | \description{ 16 | Is object a yml object? 17 | } 18 | -------------------------------------------------------------------------------- /R/addins.R: -------------------------------------------------------------------------------- 1 | #' @importFrom utils getFromNamespace 2 | launch_yaml_addin <- function() { 3 | stop_if_not_installed(c("miniUI", "shinyBS")) 4 | addin_dir <- system.file("addin", "new_yaml", package = "ymlthis") 5 | app <- shiny::shinyAppDir(addin_dir) 6 | shiny::runGadget( 7 | app, 8 | viewer = shiny::dialogViewer("New YAML", height = 700) 9 | ) 10 | } 11 | 12 | -------------------------------------------------------------------------------- /cran-comments.md: -------------------------------------------------------------------------------- 1 | ## R CMD check results 2 | 3 | 0 errors | 0 warnings | 0 note 4 | 5 | * This patch fixes a bug from the previous patch 6 | 7 | ## revdepcheck results 8 | 9 | We checked 3 reverse dependencies, comparing R CMD check results across CRAN and dev versions of this package. 10 | 11 | * We saw 0 new problems 12 | * We failed to check 0 packages 13 | 14 | 15 | -------------------------------------------------------------------------------- /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | ^LICENSE\.md$ 4 | ^README\.Rmd$ 5 | man-roxygen 6 | _pkgdown.yml 7 | _travis.yml 8 | .travis.yml 9 | ^codecov\.yml$ 10 | ^appveyor\.yml$ 11 | ^\.github$ 12 | docs 13 | ^cran-comments\.md$ 14 | ^addin.gif$ 15 | ^CRAN-RELEASE$ 16 | ^Untitled.Rmd$ 17 | ^Untitled.html$ 18 | ^rhub\.R$ 19 | ^revdep$ 20 | ^/Users/malcolmbarrett/core/active/reference/ymlthis/_pkgdown\.yml$ 21 | ^CRAN-SUBMISSION$ 22 | -------------------------------------------------------------------------------- /tests/testthat/_snaps/basic_yaml_results.md: -------------------------------------------------------------------------------- 1 | # Code chunk is rendered correctly 2 | 3 | Code 4 | rslt 5 | Output 6 | ```{r yml_example} 7 | yml_empty() %>% yml_author("Malcolm Barrett") %>% yml_output(pdf_document()) 8 | ``` 9 | 10 | # blanks are correctly cleared from author list 11 | 12 | Code 13 | author_yml 14 | Output 15 | --- 16 | author: 17 | - name: John Doe 18 | affiliation: My Uni 19 | --- 20 | 21 | -------------------------------------------------------------------------------- /ymlthis.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: No 4 | SaveWorkspace: No 5 | AlwaysSaveHistory: Yes 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: knitr 13 | LaTeX: XeLaTeX 14 | 15 | AutoAppendNewline: Yes 16 | StripTrailingWhitespace: Yes 17 | 18 | BuildType: Package 19 | PackageUseDevtools: Yes 20 | PackageInstallArgs: --no-multiarch --with-keep.source 21 | PackageRoxygenize: rd,collate,namespace 22 | -------------------------------------------------------------------------------- /tests/testthat/_snaps/markdownr.md: -------------------------------------------------------------------------------- 1 | # argument types are respected in code_chunk() 2 | 3 | Code 4 | cat(chunk1) 5 | Output 6 | ```{r fig.cap = "something"} 7 | plot(1:5) 8 | ``` 9 | 10 | --- 11 | 12 | Code 13 | cat(chunk2) 14 | Output 15 | ```{r fig.cap = label_object} 16 | plot(1:5) 17 | ``` 18 | 19 | --- 20 | 21 | Code 22 | cat(chunk3) 23 | Output 24 | ```{r fig.height = 3} 25 | plot(1:5) 26 | ``` 27 | 28 | -------------------------------------------------------------------------------- /man/last_yml.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml.R 3 | \name{last_yml} 4 | \alias{last_yml} 5 | \title{Return the most recently printed YAML} 6 | \usage{ 7 | last_yml() 8 | } 9 | \description{ 10 | ymlthis stores the most recently printed \code{yml} object; you can use 11 | \code{last_yml()} to retrieve it to modify, pass to \verb{use_*()} functions, and so 12 | on. 13 | } 14 | \examples{ 15 | yml() \%>\% 16 | yml_author("Yihui Xie") 17 | 18 | last_yml() 19 | 20 | } 21 | -------------------------------------------------------------------------------- /tests/testthat/test-markdownr.R: -------------------------------------------------------------------------------- 1 | test_that("argument types are respected in code_chunk()", { 2 | chunk1 <- ymlthis::code_chunk( 3 | plot(1:5), 4 | chunk_args = list(fig.cap = "something") 5 | ) 6 | 7 | chunk2 <- ymlthis::code_chunk( 8 | plot(1:5), 9 | chunk_args = list(fig.cap = label_object) 10 | ) 11 | 12 | chunk3 <- ymlthis::code_chunk( 13 | plot(1:5), 14 | chunk_args = list(fig.height = 3) 15 | ) 16 | 17 | expect_snapshot(cat(chunk1)) 18 | expect_snapshot(cat(chunk2)) 19 | expect_snapshot(cat(chunk3)) 20 | }) 21 | -------------------------------------------------------------------------------- /man/yml_load.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml.R 3 | \name{yml_load} 4 | \alias{yml_load} 5 | \title{Load YAML from string} 6 | \usage{ 7 | yml_load(x) 8 | } 9 | \arguments{ 10 | \item{x}{an object to pass to \code{\link[yaml:yaml.load]{yaml::yaml.load()}}} 11 | } 12 | \description{ 13 | \code{yml_load()} is a wrapper for \code{\link[yaml:yaml.load]{yaml::yaml.load()}} that also converts the 14 | object to the \code{yml} class. 15 | } 16 | \examples{ 17 | c("title: my title", "author: Malcolm Barrett") \%>\% 18 | yml_load() 19 | 20 | } 21 | -------------------------------------------------------------------------------- /man/yml_handlers.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml.R 3 | \name{yml_handlers} 4 | \alias{yml_handlers} 5 | \title{Set handlers to process the way YAML is printed} 6 | \usage{ 7 | yml_handlers() 8 | } 9 | \description{ 10 | ymlthis uses the yaml package to process and validate YAML; this package also 11 | lets you specify how fields and values are printed using a list of handler 12 | functions. \code{yml_handlers()} specifies defaults for the package used in the 13 | print statement. See \code{\link[yaml:yaml.load]{yaml::yaml.load()}} for more on specifying handlers. 14 | } 15 | -------------------------------------------------------------------------------- /tests/testthat/test-helpers_work.R: -------------------------------------------------------------------------------- 1 | if (!rmarkdown::pandoc_available()) testthat::skip("Pandoc not found") 2 | 3 | test_that("multiplication works", { 4 | 5 | x <- yml_empty() %>% 6 | yml_author("Malcolm Barrett") %>% 7 | yml_date() %>% 8 | yml_clean(TRUE) %>% 9 | yml_replace(clean = FALSE) %>% 10 | yml_discard("author") 11 | 12 | expect_equal(names(x), c("date", "clean")) 13 | expect_length(x, 2) 14 | 15 | y <- yml_empty() %>% 16 | yml_author("Malcolm Barrett") %>% 17 | yml_date() %>% 18 | yml_output( 19 | pdf_document(), 20 | html_document() 21 | ) %>% 22 | yml_discard(~ length(.x) > 1) 23 | 24 | expect_equal(names(y), c("author", "date")) 25 | expect_length(y, 2) 26 | }) 27 | -------------------------------------------------------------------------------- /tests/testthat/test-bookdown_yaml.R: -------------------------------------------------------------------------------- 1 | if (!rmarkdown::pandoc_available()) testthat::skip("Pandoc not found") 2 | if (!requireNamespace("bookdown")) testthat::skip("bookdown not found") 3 | 4 | test_that("multiplication works", { 5 | rslt <- yml_empty() %>% 6 | yml_author("Malcolm Barrett") %>% 7 | yml_date() %>% 8 | yml_output( 9 | pdf_document(keep_tex = TRUE, includes = includes2(after_body = "footer.tex")), 10 | bookdown::html_document2() 11 | ) %>% 12 | stringify_yaml() 13 | 14 | yaml_string <- "--- 15 | author: Malcolm Barrett 16 | date: '`r format(Sys.Date())`' 17 | output: 18 | pdf_document: 19 | keep_tex: true 20 | includes: 21 | after_body: footer.tex 22 | bookdown::html_document2: default 23 | ---" 24 | 25 | expect_equal(rslt, yaml_string) 26 | }) 27 | -------------------------------------------------------------------------------- /tests/testthat/test-blogdown_yaml.R: -------------------------------------------------------------------------------- 1 | if (!rmarkdown::pandoc_available()) testthat::skip("Pandoc not found") 2 | if (!requireNamespace("blogdown")) testthat::skip("blogdown not found") 3 | 4 | test_that("multiplication works", { 5 | output_yml <- yml_empty() %>% 6 | yml_output( 7 | bookdown::gitbook( 8 | lib_dir = "assets", 9 | split_by = "section", 10 | config = gitbook_config(toolbar_position = "static") 11 | ), 12 | bookdown::pdf_book(keep_tex = TRUE), 13 | bookdown::html_book(css = "toc.css") 14 | ) %>% 15 | stringify_yaml() 16 | 17 | yaml_string <- "--- 18 | output: 19 | bookdown::gitbook: 20 | lib_dir: assets 21 | split_by: section 22 | config: 23 | toolbar: 24 | position: static 25 | bookdown::pdf_book: 26 | keep_tex: true 27 | bookdown::html_book: 28 | css: toc.css 29 | ---" 30 | 31 | expect_equal(output_yml, yaml_string) 32 | }) 33 | -------------------------------------------------------------------------------- /man/as_yml.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml.R 3 | \name{as_yml} 4 | \alias{as_yml} 5 | \title{Convert to yml object} 6 | \usage{ 7 | as_yml(x) 8 | } 9 | \arguments{ 10 | \item{x}{An object, either a character vector of length 1 or list, to convert 11 | to \code{yml}.} 12 | } 13 | \value{ 14 | a \code{yml} object 15 | } 16 | \description{ 17 | \code{as_yml} is a wrapper for \code{\link[yaml:yaml.load]{yaml::yaml.load()}} that stores YAML as a \code{yml} 18 | object, which prints cleanly to the console and is easy to work with using 19 | ymlthis functions. 20 | } 21 | \examples{ 22 | 23 | x <- as_yml(" 24 | author: Hadley Wickham 25 | date: '2014-09-12' 26 | title: Tidy Data 27 | keywords: 28 | - data cleaning 29 | - data tidying 30 | - relational databases 31 | - R") 32 | 33 | x 34 | 35 | x \%>\% 36 | yml_subtitle("Hadley's Tidy Data Paper") 37 | 38 | } 39 | -------------------------------------------------------------------------------- /man/yml_verbatim.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_helpers.R 3 | \name{yml_verbatim} 4 | \alias{yml_verbatim} 5 | \title{Write YAML field or content verbatim} 6 | \usage{ 7 | yml_verbatim(x) 8 | } 9 | \arguments{ 10 | \item{x}{a character vector} 11 | } 12 | \value{ 13 | an object of class \code{verbatim} 14 | } 15 | \description{ 16 | \code{yml_verbatim()} is a helper function to write YAML precisely as given to the 17 | \verb{yml_*()} function rather than the defaults in ymlthis and yaml. ymlthis uses 18 | the yaml package to check for valid syntax; yaml and ymlthis together make 19 | decisions about how to write syntax, which can often be done in numerous 20 | valid ways. See \code{\link[yaml:as.yaml]{yaml::as.yaml()}} for more details. 21 | } 22 | \examples{ 23 | # "yes" and "no" serve as alternatives to `true` and `false`. This writes 24 | # "yes" literally. 25 | yml_verbatim("yes") 26 | } 27 | -------------------------------------------------------------------------------- /man/yml_blank.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_helpers.R 3 | \name{yml_blank} 4 | \alias{yml_blank} 5 | \alias{is_yml_blank} 6 | \title{Return a blank object to be discarded from YAML} 7 | \usage{ 8 | yml_blank() 9 | 10 | is_yml_blank(x) 11 | } 12 | \arguments{ 13 | \item{x}{a field from a \code{yml} object} 14 | } 15 | \value{ 16 | a \code{yml_blank} object 17 | } 18 | \description{ 19 | ymlthis treats \code{NULL}, \code{NA}, and other common argument defaults as literal 20 | (e.g. \code{author = NULL} will produce "author: null"). \code{yml_blank()} is a helper 21 | function to indicate that the field should not be included. \code{yml_blank()} is 22 | primarily used as a default argument for fields that should not be included 23 | by default. 24 | } 25 | \examples{ 26 | 27 | yml() \%>\% 28 | yml_replace(author = yml_blank()) \%>\% 29 | yml_discard(~is_yml_blank(.x)) 30 | 31 | 32 | } 33 | \seealso{ 34 | \code{\link[=yml_discard]{yml_discard()}}, \code{\link[=yml_replace]{yml_replace()}} 35 | } 36 | -------------------------------------------------------------------------------- /man/yml_code.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_helpers.R 3 | \name{yml_code} 4 | \alias{yml_code} 5 | \alias{yml_params_code} 6 | \title{Take code and write it as valid YAML} 7 | \usage{ 8 | yml_code(x) 9 | 10 | yml_params_code(x) 11 | } 12 | \arguments{ 13 | \item{x}{valid R code} 14 | } 15 | \value{ 16 | a character vector with class \code{verbatim} 17 | } 18 | \description{ 19 | \code{yml_code()} takes R code and writes it as valid YAML to be evaluated during 20 | knitting. Note that \code{yml_code()} does not evaluate or validate the R code but 21 | only captures it to use in the YAML field. R code needs to be formatted 22 | differently when using in the \code{params} field for parameterized reports; 23 | \code{yml_params_code} will format this correctly for you. 24 | } 25 | \examples{ 26 | 27 | yml_empty() \%>\% 28 | yml_date(yml_code(sys.Date())) 29 | 30 | yml_empty() \%>\% 31 | yml_params(date = yml_params_code(sys.Date())) 32 | 33 | } 34 | \seealso{ 35 | \code{\link[=yml_verbatim]{yml_verbatim()}} 36 | } 37 | -------------------------------------------------------------------------------- /man/includes2.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_helpers.R 3 | \name{includes2} 4 | \alias{includes2} 5 | \title{Include content within output} 6 | \usage{ 7 | includes2( 8 | in_header = yml_blank(), 9 | before_body = yml_blank(), 10 | after_body = yml_blank() 11 | ) 12 | } 13 | \arguments{ 14 | \item{in_header}{One or more files with content to be included in the header 15 | of the document.} 16 | 17 | \item{before_body}{One or more files with content to be included before the 18 | document body.} 19 | 20 | \item{after_body}{One or more files with content to be included after the 21 | document body.} 22 | } 23 | \value{ 24 | a list 25 | } 26 | \description{ 27 | \code{includes2()} is a version of the \code{includes()} helper function from rmarkdown 28 | that uses \code{yml_blank()} instead of \code{NULL} as the argument defaults, as 29 | ymlthis treats NULLs as literal YAML syntax ("null"). 30 | } 31 | \examples{ 32 | \donttest{ 33 | yml() \%>\% 34 | yml_output( 35 | pdf_document(includes = includes2(after_body = "footer.tex")) 36 | ) 37 | } 38 | } 39 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # MIT License 2 | 3 | Copyright (c) 2019 Malcolm Barrett 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 | -------------------------------------------------------------------------------- /.github/workflows/pkgdown.yaml: -------------------------------------------------------------------------------- 1 | # Workflow derived from https://github.com/r-lib/actions/tree/master/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 | release: 7 | types: [published] 8 | workflow_dispatch: 9 | 10 | name: pkgdown 11 | 12 | jobs: 13 | pkgdown: 14 | runs-on: ubuntu-latest 15 | env: 16 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 17 | steps: 18 | - uses: actions/checkout@v2 19 | 20 | - uses: r-lib/actions/setup-pandoc@v1 21 | 22 | - uses: r-lib/actions/setup-r@v1 23 | with: 24 | use-public-rspm: true 25 | 26 | - uses: r-lib/actions/setup-r-dependencies@v1 27 | with: 28 | extra-packages: pkgdown 29 | needs: website 30 | 31 | - name: Deploy package 32 | run: | 33 | export LANG=en_US.UTF-8 34 | git config --local user.name "$GITHUB_ACTOR" 35 | git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com" 36 | Rscript -e 'withr::with_options(list(crayon.enabled = TRUE), pkgdown::deploy_to_branch(new_process = FALSE))' 37 | -------------------------------------------------------------------------------- /R/read_yaml.R: -------------------------------------------------------------------------------- 1 | read_rmd <- function(path, output = c("frontmatter", "body")) { 2 | output <- match.arg(output) 3 | input_lines <- readLines(path) 4 | delimiters <- grep("^(---|\\.\\.\\.)\\s*$", input_lines) 5 | if (!validate_front_matter(delimiters, input_lines)) { 6 | return(yml_blank()) 7 | } 8 | 9 | return_lines <- (delimiters[1]):(delimiters[2]) 10 | if (output == "body") return_lines <- -return_lines 11 | 12 | input_lines[return_lines] 13 | } 14 | 15 | is_blank <- function(x) { 16 | purrr::is_empty(x) || all(grepl("^\\s*$", x)) 17 | } 18 | 19 | validate_front_matter <- function(delimiters, input_lines) { 20 | # a few conditions 21 | more_than_one <- length(delimiters) >= 2 22 | two_after_one <- (delimiters[2] - delimiters[1] > 1) 23 | all_spaces <- grepl("^---\\s*$", input_lines[delimiters[1]]) 24 | 25 | if (more_than_one && two_after_one && all_spaces) { 26 | valid <- ifelse( 27 | # if first line, valid 28 | delimiters[1] == 1, 29 | TRUE, 30 | # if not, check that what's before is blank 31 | is_blank(input_lines[1:delimiters[1] - 1]) 32 | ) 33 | return(valid) 34 | } 35 | 36 | # if none of these, YAML is not validated 37 | FALSE 38 | } 39 | -------------------------------------------------------------------------------- /man/blogdown_template.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_blogdown.R 3 | \name{blogdown_template} 4 | \alias{blogdown_template} 5 | \alias{blogdown_archetypes} 6 | \title{Create YAML based on blogdown theme archetypes} 7 | \usage{ 8 | blogdown_template(type, path = ".", theme = NULL) 9 | 10 | blogdown_archetypes(path = ".", theme = NULL) 11 | } 12 | \arguments{ 13 | \item{type}{an archetype} 14 | 15 | \item{path}{the path to your blogdown site} 16 | 17 | \item{theme}{the theme to check for archetypes. By default, 18 | \code{blogdown_template()} will attempt to read your theme from your \code{config} 19 | file.} 20 | } 21 | \value{ 22 | a \code{yml} object 23 | } 24 | \description{ 25 | \code{blogdown_template()} creates YAML based on your blogdown theme archetypes. 26 | blogdown is based on Hugo, which supports many custom themes. Each theme uses 27 | YAML in a different way. However, many come with archetypes that define the 28 | YAML or TOML. To find out which types your theme has, use 29 | \code{blogdown_archetypes()} to see what's available. Use \code{blogdown_template()} to 30 | specify the archetype and it will convert the template to YAML that you can 31 | use in your post. 32 | } 33 | -------------------------------------------------------------------------------- /man/code_chunk.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/markdownr.R 3 | \name{code_chunk} 4 | \alias{code_chunk} 5 | \alias{setup_chunk} 6 | \title{Write code chunks programmatically} 7 | \usage{ 8 | code_chunk(chunk_code, chunk_name = NULL, chunk_args = NULL) 9 | 10 | setup_chunk(chunk_code = NULL, chunk_args = list(include = FALSE)) 11 | } 12 | \arguments{ 13 | \item{chunk_code}{An expression. Surround with \code{{}} to capture multiple 14 | lines.} 15 | 16 | \item{chunk_name}{The name of the chunk} 17 | 18 | \item{chunk_args}{A \code{list} of chunk options} 19 | } 20 | \value{ 21 | a character vector 22 | } 23 | \description{ 24 | \code{code_chunk()} assembles a knitr code chunk as a character vector. 25 | \code{setup_chunk()} is a wrapper around \code{code_chunk()} to create setup chunks. By 26 | default it uses \code{include = FALSE} and inserts \code{knitr::opts_chunk$set(echo = TRUE)} into the chunk body. These are helper functions to write R Markdown 27 | bodies for \code{\link[=use_rmarkdown]{use_rmarkdown()}}. 28 | } 29 | \examples{ 30 | \donttest{ 31 | setup_chunk() 32 | 33 | code_chunk({ 34 | yml() \%>\% 35 | yml_output(pdf_document()) 36 | }, chunk_name = "yml_example") 37 | } 38 | } 39 | -------------------------------------------------------------------------------- /man/pkgdown_template.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_pkgdown.R 3 | \name{pkgdown_template} 4 | \alias{pkgdown_template} 5 | \title{Generate a full YAML template for your pkgdown site} 6 | \usage{ 7 | pkgdown_template(path = ".") 8 | } 9 | \arguments{ 10 | \item{path}{The path to your package directory} 11 | } 12 | \value{ 13 | a \code{yml} object 14 | } 15 | \description{ 16 | pkgdown includes three helpful \verb{pkgdown::template_*()} functions to generate 17 | the navbar, reference, and article YAML for the \verb{_pkgdown.yml} file. 18 | \code{pkgdown_template()} is a wrapper function that runs all three, combines 19 | them, and converts them to a \code{yml} object. You may also pass 20 | \verb{pkgdown::template_*()} functions to \code{as_yml()} to convert the individual 21 | sections. \code{pkgdown_template()} is particularly useful with 22 | \code{use_pkgdown_yml()} to write directly to the \verb{_pkgdown.yml} file. 23 | } 24 | \examples{ 25 | \dontrun{ 26 | # requires this to be a package directory 27 | pkgdown_template() \%>\% 28 | use_pkgdown_yml() 29 | } 30 | 31 | } 32 | \seealso{ 33 | \code{\link[=use_pkgdown_yml]{use_pkgdown_yml()}} 34 | 35 | Other pkgdown: 36 | \code{\link{yml_pkgdown}()} 37 | } 38 | \concept{pkgdown} 39 | -------------------------------------------------------------------------------- /NEWS.md: -------------------------------------------------------------------------------- 1 | # ymlthis 0.1.7 2 | * Fix typo in add-in checking for miniUI (#84, #85, thanks @tonycmac & 3 | @lquayle88) 4 | 5 | # ymlthis 0.1.6 6 | * `yml_author()` now correctly accepts `yml_blank()` as needed (#71) 7 | * Fix issues with new shiny release (#80) 8 | 9 | # ymlthis 0.1.5 10 | * Update citeproc functionality to rely on newer rmarkdown functions 11 | 12 | # ymlthis 0.1.3 13 | * Minor changes to address upcoming changes in shiny 1.6 14 | 15 | # ymlthis 0.1.2 16 | 17 | * updated roxygen2 rendering and removed unnecessary `...` description from `yml_pagedown_opts()` 18 | * fixed bug where removing a blank line did not work because it called the wrong object (issue #52, thanks @dchiu911) 19 | 20 | # ymlthis 0.1.1 21 | 22 | * Fixed errors in the fieldguide introduced by changes in roxygen2 7.0.0 (#50) 23 | * Add option `ymlthis.remove_blank_line`. If `TRUE`, YAML files will have their final lines removed (#42) 24 | * Synced arguments for `use_rmarkdown()` and `use_index_rmd()` and added `open_doc` argument to disable opening file (#41) 25 | * Fix bug where `usethis::write_over()` was not getting the `quiet` argument set correctly (issue #37) 26 | * Added `biblio_style` and `biblio_title` to `yml_citations()` (issue #40) 27 | 28 | # ymlthis 0.1.0 29 | 30 | * Added a `NEWS.md` file to track changes to the package. 31 | * Initial release of package 32 | -------------------------------------------------------------------------------- /man/pandoc_template_types.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/use_pandoc.R 3 | \name{pandoc_template_types} 4 | \alias{pandoc_template_types} 5 | \alias{pandoc_highlight_styles} 6 | \alias{use_pandoc_template} 7 | \alias{use_pandoc_highlight_style} 8 | \title{Use pandoc templates and custom highlight themes} 9 | \usage{ 10 | pandoc_template_types() 11 | 12 | pandoc_highlight_styles() 13 | 14 | use_pandoc_template(type, path, source = c("rmarkdown", "pandoc")) 15 | 16 | use_pandoc_highlight_style(theme, path) 17 | } 18 | \arguments{ 19 | \item{type}{The template type} 20 | 21 | \item{path}{The path to write the file to} 22 | 23 | \item{source}{The template source ("pandoc" or "rmarkdown")} 24 | 25 | \item{theme}{The name of the theme} 26 | } 27 | \value{ 28 | a character vector 29 | } 30 | \description{ 31 | Pandoc has several built in templates and code highlighting themes that can 32 | be customized and included in the \code{template} and \code{highlight-style} YAML 33 | fields, respectively. \code{pandoc_template_types()} and 34 | \code{pandoc_highlight_styles()} return the available templates and highlight 35 | styles in pandoc, respectively. \code{use_pandoc_template()} creates a new file 36 | based on a template from pandoc or R Markdown and 37 | \code{use_pandoc_highlight_style()} creates a new highlight theme file based on an 38 | existing pandoc theme. 39 | } 40 | -------------------------------------------------------------------------------- /.github/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Code of Conduct 2 | 3 | As contributors and maintainers of this project, we pledge to respect all people who 4 | contribute through reporting issues, posting feature requests, updating documentation, 5 | submitting pull requests or patches, and other activities. 6 | 7 | We are committed to making participation in this project a harassment-free experience for 8 | everyone, regardless of level of experience, gender, gender identity and expression, 9 | sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion. 10 | 11 | Examples of unacceptable behavior by participants include the use of sexual language or 12 | imagery, derogatory comments or personal attacks, trolling, public or private harassment, 13 | insults, or other unprofessional conduct. 14 | 15 | Project maintainers have the right and responsibility to remove, edit, or reject comments, 16 | commits, code, wiki edits, issues, and other contributions that are not aligned to this 17 | Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed 18 | from the project team. 19 | 20 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by 21 | opening an issue or contacting one or more of the project maintainers. 22 | 23 | This Code of Conduct is adapted from the Contributor Covenant 24 | (https://www.contributor-covenant.org), version 1.0.0, available at 25 | https://contributor-covenant.org/version/1/0/0/. 26 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: ymlthis 2 | Title: Write 'YAML' for 'R Markdown', 'bookdown', 'blogdown', and More 3 | Version: 0.1.7 4 | Authors@R: c( 5 | person("Malcolm", "Barrett", , "malcolmbarrett@gmail.com", role = c("aut", "cre"), 6 | comment = c(ORCID = "0000-0003-0299-5825")), 7 | person("Richard", "Iannone", , "rich@rstudio.com", role = "aut", 8 | comment = c(ORCID = "0000-0003-3925-190X")), 9 | person("RStudio", role = c("cph", "fnd")) 10 | ) 11 | Description: Write 'YAML' front matter for R Markdown and related 12 | documents. Work with 'YAML' objects more naturally and write the 13 | resulting 'YAML' to your clipboard or to 'YAML' files related to your 14 | project. 15 | License: MIT + file LICENSE 16 | URL: https://ymlthis.r-lib.org, https://github.com/r-lib/ymlthis 17 | BugReports: https://github.com/r-lib/ymlthis/issues 18 | Depends: 19 | R (>= 3.2) 20 | Imports: 21 | crayon, 22 | fs, 23 | glue, 24 | magrittr, 25 | purrr (>= 0.3.2), 26 | rlang (>= 0.4.10), 27 | rmarkdown (>= 2.10), 28 | rstudioapi, 29 | stringr, 30 | usethis (>= 1.5.0), 31 | whoami, 32 | withr, 33 | yaml 34 | Suggests: 35 | blogdown, 36 | bookdown, 37 | covr, 38 | knitr, 39 | miniUI, 40 | pkgdown, 41 | prettydoc, 42 | roxygen2 (>= 7.0.0), 43 | shiny, 44 | shinyBS, 45 | spelling, 46 | testthat (>= 3.0.0), 47 | xaringan 48 | VignetteBuilder: 49 | knitr 50 | Config/testthat/edition: 3 51 | Encoding: UTF-8 52 | Language: en-US 53 | Roxygen: list(markdown = TRUE) 54 | RoxygenNote: 7.2.0 55 | -------------------------------------------------------------------------------- /man/asis_yaml_output.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml.R 3 | \name{asis_yaml_output} 4 | \alias{asis_yaml_output} 5 | \title{Export yml object as a YAML knitr code chunk} 6 | \usage{ 7 | asis_yaml_output(.yml, fences = TRUE) 8 | } 9 | \arguments{ 10 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 11 | a \verb{yml_*()} function} 12 | 13 | \item{fences}{Logical. Write fences ("---") before and after YAML?} 14 | } 15 | \description{ 16 | \code{asis_yaml_output()} exports a \code{yml} object as a YAML knitr code chunk 17 | instead of as an R object. Doing so adds code highlighting for YAML syntax. 18 | } 19 | \seealso{ 20 | Other yml: 21 | \code{\link{bib2yml}()}, 22 | \code{\link{draw_yml_tree}()}, 23 | \code{\link{has_field}()}, 24 | \code{\link{read_json}()}, 25 | \code{\link{use_yml_defaults}()}, 26 | \code{\link{use_yml_file}()}, 27 | \code{\link{use_yml}()}, 28 | \code{\link{yml_author}()}, 29 | \code{\link{yml_blogdown_opts}()}, 30 | \code{\link{yml_bookdown_opts}()}, 31 | \code{\link{yml_citations}()}, 32 | \code{\link{yml_clean}()}, 33 | \code{\link{yml_distill_opts}()}, 34 | \code{\link{yml_latex_opts}()}, 35 | \code{\link{yml_output}()}, 36 | \code{\link{yml_pagedown_opts}()}, 37 | \code{\link{yml_params}()}, 38 | \code{\link{yml_pkgdown}()}, 39 | \code{\link{yml_reference}()}, 40 | \code{\link{yml_replace}()}, 41 | \code{\link{yml_resource_files}()}, 42 | \code{\link{yml_rsconnect_email}()}, 43 | \code{\link{yml_rticles_opts}()}, 44 | \code{\link{yml_runtime}()}, 45 | \code{\link{yml_site_opts}()}, 46 | \code{\link{yml_toc}()}, 47 | \code{\link{yml_vignette}()} 48 | } 49 | \concept{yml} 50 | -------------------------------------------------------------------------------- /inst/WORDLIST: -------------------------------------------------------------------------------- 1 | Analytics 2 | CJKmainfont 3 | CMD 4 | CN 5 | CSL 6 | Catalogue 7 | Codecov 8 | DOI 9 | Disqus 10 | Fieldguide 11 | Hadley 12 | IETF 13 | Instapaper 14 | JSON 15 | Javascript 16 | Lifecycle 17 | LinkedIn 18 | NULLs 19 | ORCID 20 | POSIXt 21 | Pandoc 22 | Rmd 23 | TOC 24 | TOML 25 | TW 26 | UI 27 | VK 28 | Weibo 29 | Wickham 30 | YAML 31 | ar 32 | az 33 | bg 34 | biblatex 35 | bibtex 36 | blogdown 37 | bookdown 38 | bootswatch 39 | bs 40 | citeproc 41 | csv 42 | cy 43 | da 44 | datepicker 45 | de 46 | dev 47 | devtools 48 | disqus 49 | distill's 50 | docsearch 51 | dplyr 52 | dvipsnames 53 | el 54 | eo 55 | et 56 | eu 57 | facebook 58 | favicon 59 | fi 60 | fieldguide 61 | flexdashboard 62 | fo 63 | fontenc 64 | fontspec 65 | gl 66 | grDevices 67 | hu 68 | hy 69 | iframe 70 | issn 71 | ja 72 | ka 73 | kh 74 | kk 75 | knitr 76 | ko 77 | kr 78 | learnr 79 | linkedin 80 | longtable 81 | lt 82 | lualatex 83 | lv 84 | mainfont 85 | mathfont 86 | microtype 87 | miniUI 88 | misspecify 89 | mk 90 | mn 91 | monofont 92 | morem 93 | natbib 94 | navbar 95 | navbars 96 | nb 97 | nl 98 | oneside 99 | pagedown 100 | pandoc 101 | pdflatex 102 | pinterest 103 | pkgdown 104 | png 105 | pre 106 | programmatically 107 | purrr 108 | px 109 | revealjs 110 | rmarkdown 111 | ro 112 | roxygen 113 | rticles 114 | ru 115 | sansfont 116 | searchability 117 | setspace 118 | shortname 119 | sk 120 | sl 121 | sr 122 | strftime 123 | subsubsection 124 | subtag 125 | sv 126 | svgnames 127 | sw 128 | th 129 | tooltip 130 | uk 131 | usethis 132 | whoami 133 | xaringan 134 | xcolor 135 | xecjk 136 | xelatex 137 | yaml 138 | yml 139 | zh 140 | -------------------------------------------------------------------------------- /man/has_field.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_helpers.R 3 | \name{has_field} 4 | \alias{has_field} 5 | \title{Check if field exists in YAML} 6 | \usage{ 7 | has_field(.yml, field) 8 | } 9 | \arguments{ 10 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 11 | a \verb{yml_*()} function} 12 | 13 | \item{field}{A character vector, the name of the field(s) to check for} 14 | } 15 | \value{ 16 | logical 17 | } 18 | \description{ 19 | \code{has_field()} retrieves the names of all fields (including nested fields) and 20 | checks if \code{field} is among them. 21 | } 22 | \examples{ 23 | 24 | has_field(yml(), "author") 25 | has_field(yml(), "toc") 26 | 27 | } 28 | \seealso{ 29 | Other yml: 30 | \code{\link{asis_yaml_output}()}, 31 | \code{\link{bib2yml}()}, 32 | \code{\link{draw_yml_tree}()}, 33 | \code{\link{read_json}()}, 34 | \code{\link{use_yml_defaults}()}, 35 | \code{\link{use_yml_file}()}, 36 | \code{\link{use_yml}()}, 37 | \code{\link{yml_author}()}, 38 | \code{\link{yml_blogdown_opts}()}, 39 | \code{\link{yml_bookdown_opts}()}, 40 | \code{\link{yml_citations}()}, 41 | \code{\link{yml_clean}()}, 42 | \code{\link{yml_distill_opts}()}, 43 | \code{\link{yml_latex_opts}()}, 44 | \code{\link{yml_output}()}, 45 | \code{\link{yml_pagedown_opts}()}, 46 | \code{\link{yml_params}()}, 47 | \code{\link{yml_pkgdown}()}, 48 | \code{\link{yml_reference}()}, 49 | \code{\link{yml_replace}()}, 50 | \code{\link{yml_resource_files}()}, 51 | \code{\link{yml_rsconnect_email}()}, 52 | \code{\link{yml_rticles_opts}()}, 53 | \code{\link{yml_runtime}()}, 54 | \code{\link{yml_site_opts}()}, 55 | \code{\link{yml_toc}()}, 56 | \code{\link{yml_vignette}()} 57 | } 58 | \concept{yml} 59 | -------------------------------------------------------------------------------- /man/draw_yml_tree.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/draw_tree.R 3 | \name{draw_yml_tree} 4 | \alias{draw_yml_tree} 5 | \title{Draw an tree of YAML hierarchy} 6 | \usage{ 7 | draw_yml_tree(.yml = last_yml(), indent = "") 8 | } 9 | \arguments{ 10 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 11 | a \verb{yml_*()} function} 12 | 13 | \item{indent}{a character vector used to indent the tree} 14 | } 15 | \value{ 16 | invisibly, \code{.yml} 17 | } 18 | \description{ 19 | \code{draw_yml_tree()} draws an ASCII tree of the hierarchy of a given \code{yml} 20 | object to the console. 21 | } 22 | \examples{ 23 | # draw the most recently used `yml` 24 | draw_yml_tree() 25 | \donttest{ 26 | yml() \%>\% 27 | yml_output( 28 | pdf_document(keep_tex = TRUE), 29 | html_document() 30 | ) \%>\% 31 | draw_yml_tree() 32 | } 33 | } 34 | \seealso{ 35 | Other yml: 36 | \code{\link{asis_yaml_output}()}, 37 | \code{\link{bib2yml}()}, 38 | \code{\link{has_field}()}, 39 | \code{\link{read_json}()}, 40 | \code{\link{use_yml_defaults}()}, 41 | \code{\link{use_yml_file}()}, 42 | \code{\link{use_yml}()}, 43 | \code{\link{yml_author}()}, 44 | \code{\link{yml_blogdown_opts}()}, 45 | \code{\link{yml_bookdown_opts}()}, 46 | \code{\link{yml_citations}()}, 47 | \code{\link{yml_clean}()}, 48 | \code{\link{yml_distill_opts}()}, 49 | \code{\link{yml_latex_opts}()}, 50 | \code{\link{yml_output}()}, 51 | \code{\link{yml_pagedown_opts}()}, 52 | \code{\link{yml_params}()}, 53 | \code{\link{yml_pkgdown}()}, 54 | \code{\link{yml_reference}()}, 55 | \code{\link{yml_replace}()}, 56 | \code{\link{yml_resource_files}()}, 57 | \code{\link{yml_rsconnect_email}()}, 58 | \code{\link{yml_rticles_opts}()}, 59 | \code{\link{yml_runtime}()}, 60 | \code{\link{yml_site_opts}()}, 61 | \code{\link{yml_toc}()}, 62 | \code{\link{yml_vignette}()} 63 | } 64 | \concept{yml} 65 | -------------------------------------------------------------------------------- /tests/testthat/test-rmarkdown_functions.R: -------------------------------------------------------------------------------- 1 | if (!requireNamespace("shiny", quietly = TRUE)) skip() 2 | 3 | expect_shiny_list <- function(x, ...) { 4 | expect_type(x, "list") 5 | expect_equal(x, list(...)) 6 | } 7 | 8 | test_that("shiny functions return correctly", { 9 | checkbox_param <- shiny_checkbox(label = "checkbox") 10 | expect_shiny_list(checkbox_param, input = "checkbox", label = "checkbox") 11 | checkbox_opt <- shiny_checkbox(label = "checkbox", value = TRUE) 12 | expect_shiny_list(checkbox_opt, input = "checkbox", label = "checkbox", value = TRUE) 13 | 14 | date_param <- shiny_date(label = "date", autoclose = FALSE) 15 | expect_shiny_list(date_param, input = "date", label = "date", autoclose = FALSE) 16 | 17 | file_param <- shiny_file(label = "file", multiple = TRUE) 18 | expect_shiny_list(file_param, input = "file", label = "file", multiple = TRUE) 19 | 20 | numeric_param <- shiny_numeric(label = "numeric", value = 23) 21 | expect_shiny_list(numeric_param, input = "numeric", label = "numeric", value = 23) 22 | 23 | password_param <- shiny_password(label = "password", value = "x23") 24 | expect_shiny_list(password_param, input = "password", label = "password", value = "x23") 25 | 26 | radio_param <- shiny_radio(label = "radio", choices = c("yes", "no")) 27 | expect_shiny_list(radio_param, input = "radio", label = "radio", choices = c("yes", "no")) 28 | 29 | select_param <- shiny_select(label = "select", choices = c("yes", "no")) 30 | expect_shiny_list(select_param, input = "select", label = "select", choices = c("yes", "no")) 31 | 32 | slider_param <- shiny_slider(label = "slider", min = 0, max = 1, value = .5) 33 | expect_shiny_list(slider_param, input = "slider", label = "slider", min = 0, max = 1, value = .5) 34 | 35 | text_param <- shiny_text(label = "text", value = "shiny text") 36 | expect_shiny_list(text_param, input = "text", label = "text", value = "shiny text") 37 | }) 38 | -------------------------------------------------------------------------------- /man/bib2yml.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_citations.R 3 | \name{bib2yml} 4 | \alias{bib2yml} 5 | \title{Convert bib files to YAML} 6 | \usage{ 7 | bib2yml(.yml = NULL, path) 8 | } 9 | \arguments{ 10 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 11 | a \verb{yml_*()} function} 12 | 13 | \item{path}{a path to the .bib file} 14 | } 15 | \value{ 16 | a \code{yml} object 17 | } 18 | \description{ 19 | \code{bib2yml()} uses pandoc to convert a .bib file to YAML. It also accepts an 20 | optional \code{yml} object to prepend to the the YAML from the .bib file. If you 21 | want to cite several R packages, see \code{\link[knitr:write_bib]{knitr::write_bib()}} to write a 22 | bibliography file and convert it with \code{bib2yml()}. 23 | } 24 | \seealso{ 25 | Other yml: 26 | \code{\link{asis_yaml_output}()}, 27 | \code{\link{draw_yml_tree}()}, 28 | \code{\link{has_field}()}, 29 | \code{\link{read_json}()}, 30 | \code{\link{use_yml_defaults}()}, 31 | \code{\link{use_yml_file}()}, 32 | \code{\link{use_yml}()}, 33 | \code{\link{yml_author}()}, 34 | \code{\link{yml_blogdown_opts}()}, 35 | \code{\link{yml_bookdown_opts}()}, 36 | \code{\link{yml_citations}()}, 37 | \code{\link{yml_clean}()}, 38 | \code{\link{yml_distill_opts}()}, 39 | \code{\link{yml_latex_opts}()}, 40 | \code{\link{yml_output}()}, 41 | \code{\link{yml_pagedown_opts}()}, 42 | \code{\link{yml_params}()}, 43 | \code{\link{yml_pkgdown}()}, 44 | \code{\link{yml_reference}()}, 45 | \code{\link{yml_replace}()}, 46 | \code{\link{yml_resource_files}()}, 47 | \code{\link{yml_rsconnect_email}()}, 48 | \code{\link{yml_rticles_opts}()}, 49 | \code{\link{yml_runtime}()}, 50 | \code{\link{yml_site_opts}()}, 51 | \code{\link{yml_toc}()}, 52 | \code{\link{yml_vignette}()} 53 | 54 | Other citations: 55 | \code{\link{yml_citations}()}, 56 | \code{\link{yml_reference}()} 57 | } 58 | \concept{citations} 59 | \concept{yml} 60 | -------------------------------------------------------------------------------- /man/yml_resource_files.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_rmarkdown.R 3 | \name{yml_resource_files} 4 | \alias{yml_resource_files} 5 | \title{Add external resource files to R Markdown document} 6 | \usage{ 7 | yml_resource_files(.yml, resource_files) 8 | } 9 | \arguments{ 10 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 11 | a \verb{yml_*()} function} 12 | 13 | \item{resource_files}{A path to a file, directory, or a wildcard pattern 14 | (such as "data/*.csv")} 15 | } 16 | \value{ 17 | a \code{yml} object 18 | } 19 | \description{ 20 | The \code{resource_files} field specifies a character vectors of paths to external 21 | resources to include in the output, e.g. files that are necessary for 22 | rendering. These files are handled with 23 | \code{rmarkdown::find_external_resources()}. 24 | } 25 | \examples{ 26 | 27 | yml() \%>\% 28 | yml_resource_files(c("data/mydata.csv", "images/figure.png")) 29 | } 30 | \seealso{ 31 | Other yml: 32 | \code{\link{asis_yaml_output}()}, 33 | \code{\link{bib2yml}()}, 34 | \code{\link{draw_yml_tree}()}, 35 | \code{\link{has_field}()}, 36 | \code{\link{read_json}()}, 37 | \code{\link{use_yml_defaults}()}, 38 | \code{\link{use_yml_file}()}, 39 | \code{\link{use_yml}()}, 40 | \code{\link{yml_author}()}, 41 | \code{\link{yml_blogdown_opts}()}, 42 | \code{\link{yml_bookdown_opts}()}, 43 | \code{\link{yml_citations}()}, 44 | \code{\link{yml_clean}()}, 45 | \code{\link{yml_distill_opts}()}, 46 | \code{\link{yml_latex_opts}()}, 47 | \code{\link{yml_output}()}, 48 | \code{\link{yml_pagedown_opts}()}, 49 | \code{\link{yml_params}()}, 50 | \code{\link{yml_pkgdown}()}, 51 | \code{\link{yml_reference}()}, 52 | \code{\link{yml_replace}()}, 53 | \code{\link{yml_rsconnect_email}()}, 54 | \code{\link{yml_rticles_opts}()}, 55 | \code{\link{yml_runtime}()}, 56 | \code{\link{yml_site_opts}()}, 57 | \code{\link{yml_toc}()}, 58 | \code{\link{yml_vignette}()} 59 | } 60 | \concept{yml} 61 | -------------------------------------------------------------------------------- /.github/workflows/R-CMD-check.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 | # 4 | # NOTE: This workflow is overkill for most R packages and 5 | # check-standard.yaml is likely a better choice. 6 | # usethis::use_github_action("check-standard") will install it. 7 | on: 8 | push: 9 | branches: [main, master] 10 | pull_request: 11 | branches: [main, master] 12 | 13 | name: R-CMD-check 14 | 15 | jobs: 16 | R-CMD-check: 17 | runs-on: ${{ matrix.config.os }} 18 | 19 | name: ${{ matrix.config.os }} (${{ matrix.config.r }}) 20 | 21 | strategy: 22 | fail-fast: false 23 | matrix: 24 | config: 25 | - {os: macOS-latest, r: 'release'} 26 | 27 | - {os: windows-latest, r: 'release'} 28 | # Use 3.6 to trigger usage of RTools35 29 | - {os: windows-latest, r: '3.6'} 30 | 31 | # Use older ubuntu to maximise backward compatibility 32 | - {os: ubuntu-18.04, r: 'devel', http-user-agent: 'release'} 33 | - {os: ubuntu-18.04, r: 'release'} 34 | - {os: ubuntu-18.04, r: 'oldrel-1'} 35 | - {os: ubuntu-18.04, r: 'oldrel-2'} 36 | - {os: ubuntu-18.04, r: 'oldrel-3'} 37 | - {os: ubuntu-18.04, r: 'oldrel-4'} 38 | 39 | env: 40 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 41 | R_KEEP_PKG_SOURCE: yes 42 | 43 | steps: 44 | - uses: actions/checkout@v2 45 | 46 | - uses: r-lib/actions/setup-pandoc@v2 47 | 48 | - uses: r-lib/actions/setup-r@v2 49 | with: 50 | r-version: ${{ matrix.config.r }} 51 | http-user-agent: ${{ matrix.config.http-user-agent }} 52 | use-public-rspm: true 53 | 54 | - uses: r-lib/actions/setup-r-dependencies@v2 55 | with: 56 | extra-packages: any::rcmdcheck 57 | needs: check 58 | 59 | - uses: r-lib/actions/check-r-package@v2 60 | with: 61 | upload-snapshots: true 62 | -------------------------------------------------------------------------------- /_pkgdown.yml: -------------------------------------------------------------------------------- 1 | reference: 2 | - title: All functions 3 | contents: 4 | - '`as_yml`' 5 | - '`asis_yaml_output`' 6 | - '`bib2yml`' 7 | - '`blogdown_template`' 8 | - '`code_chunk`' 9 | - '`draw_yml_tree`' 10 | - '`gitbook_config`' 11 | - '`has_field`' 12 | - '`includes2`' 13 | - '`is_yml`' 14 | - '`last_yml`' 15 | - '`pagedown_business_card_template`' 16 | - '`pandoc_template_types`' 17 | - '`pkgdown_template`' 18 | - '`read_json`' 19 | - '`use_yml_file`' 20 | - '`use_yml`' 21 | - '`use_yml_defaults`' 22 | - '`yml`' 23 | - '`yml_author`' 24 | - '`yml_blank`' 25 | - '`yml_blogdown_opts`' 26 | - '`yml_bookdown_opts`' 27 | - '`yml_citations`' 28 | - '`yml_clean`' 29 | - '`yml_code`' 30 | - '`yml_distill_opts`' 31 | - '`yml_handlers`' 32 | - '`yml_latex_opts`' 33 | - '`yml_load`' 34 | - '`yml_output`' 35 | - '`yml_pagedown_opts`' 36 | - '`yml_params`' 37 | - '`yml_pkgdown`' 38 | - '`yml_reference`' 39 | - '`yml_replace`' 40 | - '`yml_resource_files`' 41 | - '`yml_rsconnect_email`' 42 | - '`yml_rticles_opts`' 43 | - '`yml_runtime`' 44 | - '`yml_site_opts`' 45 | - '`yml_toc`' 46 | - '`yml_verbatim`' 47 | - '`yml_vignette`' 48 | articles: 49 | - title: All vignettes 50 | desc: null 51 | contents: 52 | - '`introduction-to-ymlthis`' 53 | - '`yaml-fieldguide`' 54 | - '`yaml-overview`' 55 | navbar: 56 | structure: 57 | left: 58 | - intro 59 | - reference 60 | - articles 61 | - tutorials 62 | - news 63 | right: github 64 | components: 65 | reference: 66 | text: Reference 67 | href: reference/index.html 68 | news: 69 | text: Changelog 70 | href: news/index.html 71 | github: 72 | icon: fab fa-github fa-lg 73 | href: https://github.com/r-lib/ymlthis/ 74 | aria-label: github 75 | articles: 76 | text: Articles 77 | menu: 78 | - text: An Introduction to ymlthis 79 | href: articles/introduction-to-ymlthis.html 80 | - text: The YAML Fieldguide 81 | href: articles/yaml-fieldguide.html 82 | - text: 'YAML: an Overview' 83 | href: articles/yaml-overview.html 84 | 85 | -------------------------------------------------------------------------------- /man/yml_clean.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_rmarkdown.R 3 | \name{yml_clean} 4 | \alias{yml_clean} 5 | \title{Remove intermediate rendering files} 6 | \usage{ 7 | yml_clean(.yml, clean) 8 | } 9 | \arguments{ 10 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 11 | a \verb{yml_*()} function} 12 | 13 | \item{clean}{Logical. Remove intermediate files that are created while making 14 | the R Markdown document?} 15 | } 16 | \value{ 17 | a \code{yml} object 18 | } 19 | \description{ 20 | R Markdown may create many documents while rendering the final product, for 21 | instance by using knitr to turn the R Markdown file to a Markdown file and 22 | then using Pandoc to convert to the final output. The \code{clean} field tells R 23 | Markdown whether or not to remove these files. 24 | } 25 | \examples{ 26 | 27 | yml() \%>\% 28 | # keep intermediate files 29 | yml_clean(FALSE) 30 | 31 | } 32 | \seealso{ 33 | Other yml: 34 | \code{\link{asis_yaml_output}()}, 35 | \code{\link{bib2yml}()}, 36 | \code{\link{draw_yml_tree}()}, 37 | \code{\link{has_field}()}, 38 | \code{\link{read_json}()}, 39 | \code{\link{use_yml_defaults}()}, 40 | \code{\link{use_yml_file}()}, 41 | \code{\link{use_yml}()}, 42 | \code{\link{yml_author}()}, 43 | \code{\link{yml_blogdown_opts}()}, 44 | \code{\link{yml_bookdown_opts}()}, 45 | \code{\link{yml_citations}()}, 46 | \code{\link{yml_distill_opts}()}, 47 | \code{\link{yml_latex_opts}()}, 48 | \code{\link{yml_output}()}, 49 | \code{\link{yml_pagedown_opts}()}, 50 | \code{\link{yml_params}()}, 51 | \code{\link{yml_pkgdown}()}, 52 | \code{\link{yml_reference}()}, 53 | \code{\link{yml_replace}()}, 54 | \code{\link{yml_resource_files}()}, 55 | \code{\link{yml_rsconnect_email}()}, 56 | \code{\link{yml_rticles_opts}()}, 57 | \code{\link{yml_runtime}()}, 58 | \code{\link{yml_site_opts}()}, 59 | \code{\link{yml_toc}()}, 60 | \code{\link{yml_vignette}()} 61 | 62 | Other R Markdown: 63 | \code{\link{yml_params}()}, 64 | \code{\link{yml_runtime}()}, 65 | \code{\link{yml_site_opts}()}, 66 | \code{\link{yml_vignette}()} 67 | } 68 | \concept{R Markdown} 69 | \concept{yml} 70 | -------------------------------------------------------------------------------- /tests/testthat/test-basic_yaml_results.R: -------------------------------------------------------------------------------- 1 | if (!rmarkdown::pandoc_available()) testthat::skip("Pandoc not found") 2 | 3 | test_that("Basic YAML is rendered correctly", { 4 | rslt <- yml_empty() %>% 5 | yml_author( 6 | c("Yihui Xie", "Hadley Wickham"), 7 | affiliation = rep("RStudio", 2) 8 | ) %>% 9 | yml_date("07/04/2019") %>% 10 | yml_output( 11 | pdf_document( 12 | keep_tex = TRUE, 13 | includes = includes2(after_body = "footer.tex") 14 | ) 15 | ) %>% 16 | yml_latex_opts(biblio_style = "apalike") %>% 17 | stringify_yaml() 18 | 19 | yaml_string <- "--- 20 | author: 21 | - name: Yihui Xie 22 | affiliation: RStudio 23 | - name: Hadley Wickham 24 | affiliation: RStudio 25 | date: 07/04/2019 26 | output: 27 | pdf_document: 28 | keep_tex: true 29 | includes: 30 | after_body: footer.tex 31 | biblio-style: apalike 32 | ---" 33 | expect_equal(rslt, yaml_string) 34 | }) 35 | 36 | test_that("output fields render correctly", { 37 | rslts <- yml_empty() %>% 38 | yml_output(html_document()) %>% 39 | stringify_yaml() 40 | 41 | yaml_string <- "--- 42 | output: html_document 43 | ---" 44 | expect_equal(rslts, yaml_string) 45 | }) 46 | 47 | test_that("LaTeX options render correctly", { 48 | rslt <- yml_empty() %>% 49 | yml_author("Malcolm Barrett") %>% 50 | yml_output(pdf_document()) %>% 51 | yml_latex_opts( 52 | fontfamily = "Fira Sans Thin", 53 | fontsize = "11pt", 54 | links_as_notes = TRUE 55 | ) %>% 56 | stringify_yaml() 57 | 58 | yaml_string <- "--- 59 | author: Malcolm Barrett 60 | output: pdf_document 61 | fontfamily: Fira Sans Thin 62 | fontsize: 11pt 63 | links-as-notes: true 64 | ---" 65 | 66 | expect_equal(rslt, yaml_string) 67 | }) 68 | 69 | test_that("Code chunk is rendered correctly", { 70 | rslt <- code_chunk({ 71 | yml_empty() %>% 72 | yml_author("Malcolm Barrett") %>% 73 | yml_output(pdf_document()) 74 | }, chunk_name = "yml_example") 75 | 76 | expect_snapshot(rslt) 77 | }) 78 | 79 | test_that("blanks are correctly cleared from author list", { 80 | author_yml <- yml_empty() %>% 81 | yml_distill_author( 82 | name = "John Doe", 83 | affiliation = "My Uni" 84 | ) 85 | 86 | expect_snapshot(author_yml) 87 | }) 88 | 89 | -------------------------------------------------------------------------------- /R/yml_replace.R: -------------------------------------------------------------------------------- 1 | #' Replace, pluck, or discard top-level YAML fields 2 | #' 3 | #' `yml_replace()` replaces a named field with another value. As opposed to 4 | #' duplicating top-level fields with other functions, explicitly replacing them 5 | #' with `yml_replace()` will not raise a warning. `yml_discard()` removes values 6 | #' given either a character vector of names or a purrr-style lambda with a 7 | #' predicate (~ predicate); see the examples. `yml_pluck()` and `yml_chuck()` 8 | #' are wrappers around [purrr::pluck()] and [purrr::chuck()] that return `yml` 9 | #' objects. 10 | #' 11 | #' @template describe_yml_param 12 | #' @param .rid a character vector of fields to remove or a purrr-style lambda 13 | #' with a predicate (~ predicate) where fields that are `TRUE` will be 14 | #' discarded 15 | #' @template describe_dots_param 16 | #' 17 | #' @template describe_yml_output 18 | #' @export 19 | #' 20 | #' @examples 21 | #'\donttest{ 22 | #' yml() %>% 23 | #' yml_clean(TRUE) %>% 24 | #' yml_replace(clean = FALSE) %>% 25 | #' yml_discard("author") 26 | #' 27 | #' yml() %>% 28 | #' yml_output( 29 | #' pdf_document(), 30 | #' html_document() 31 | #' )%>% 32 | #' yml_discard(~ length(.x) > 1) 33 | #'} 34 | #' 35 | yml_replace <- function(.yml, ...) { 36 | new <- list(...) 37 | .yml[names(new)] <- new 38 | 39 | .yml 40 | } 41 | 42 | #' @export 43 | #' @rdname yml_replace 44 | yml_discard <- function(.yml, .rid) { 45 | if (is.character(.rid)) { 46 | return( 47 | .yml[names(.yml) %nin% .rid] %>% 48 | as_yml() 49 | ) 50 | } 51 | 52 | if (is.numeric(.rid)) { 53 | return( 54 | .yml[-.rid] %>% 55 | as_yml() 56 | ) 57 | } 58 | 59 | if (rlang::is_formula(.rid)) { 60 | return( 61 | purrr::discard(.yml, .rid) %>% 62 | as_yml() 63 | ) 64 | } 65 | 66 | msg <- glue::glue( 67 | "`.rid` must be a character vector of field names \\ 68 | or a formula specifying a predicate" 69 | ) 70 | stop(msg, call. = FALSE) 71 | } 72 | 73 | #' @export 74 | #' @rdname yml_replace 75 | yml_pluck <- function(.yml, ...) { 76 | purrr::pluck(.yml, ..., .default = list()) %>% 77 | as_yml() 78 | } 79 | 80 | #' @export 81 | #' @rdname yml_replace 82 | yml_chuck <- function(.yml, ...) { 83 | purrr::chuck(.yml, ...) %>% 84 | as_yml() 85 | } 86 | 87 | 88 | -------------------------------------------------------------------------------- /man/yml_toc.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_rmarkdown.R 3 | \name{yml_toc} 4 | \alias{yml_toc} 5 | \title{Specify Table of Contents options} 6 | \usage{ 7 | yml_toc( 8 | .yml, 9 | toc = yml_blank(), 10 | toc_depth = yml_blank(), 11 | toc_title = yml_blank(), 12 | ... 13 | ) 14 | } 15 | \arguments{ 16 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 17 | a \verb{yml_*()} function} 18 | 19 | \item{toc}{Logical. Use a Table of Contents?} 20 | 21 | \item{toc_depth}{An integer. The depth of headers to use in the TOC. Note 22 | that the actual YAML field is \code{toc-depth}.} 23 | 24 | \item{toc_title}{The title of the TOC. Note that the actual YAML field is 25 | \code{toc-title}.} 26 | 27 | \item{...}{additional named R objects, such as characters or lists, to 28 | transform into YAML} 29 | } 30 | \value{ 31 | a \code{yml} object 32 | } 33 | \description{ 34 | It's generally better to specify Table of Contents in the output function you 35 | are using so you have a clearer idea of your options (e.g. \code{html_document(toc = TRUE, toc_float = TRUE)}). However, you can also generally specify at the 36 | top level of YAML. 37 | } 38 | \examples{ 39 | 40 | yml() \%>\% 41 | yml_toc(toc = TRUE, toc_depth = 1, toc_title = "Article Outline") 42 | 43 | } 44 | \seealso{ 45 | Other yml: 46 | \code{\link{asis_yaml_output}()}, 47 | \code{\link{bib2yml}()}, 48 | \code{\link{draw_yml_tree}()}, 49 | \code{\link{has_field}()}, 50 | \code{\link{read_json}()}, 51 | \code{\link{use_yml_defaults}()}, 52 | \code{\link{use_yml_file}()}, 53 | \code{\link{use_yml}()}, 54 | \code{\link{yml_author}()}, 55 | \code{\link{yml_blogdown_opts}()}, 56 | \code{\link{yml_bookdown_opts}()}, 57 | \code{\link{yml_citations}()}, 58 | \code{\link{yml_clean}()}, 59 | \code{\link{yml_distill_opts}()}, 60 | \code{\link{yml_latex_opts}()}, 61 | \code{\link{yml_output}()}, 62 | \code{\link{yml_pagedown_opts}()}, 63 | \code{\link{yml_params}()}, 64 | \code{\link{yml_pkgdown}()}, 65 | \code{\link{yml_reference}()}, 66 | \code{\link{yml_replace}()}, 67 | \code{\link{yml_resource_files}()}, 68 | \code{\link{yml_rsconnect_email}()}, 69 | \code{\link{yml_rticles_opts}()}, 70 | \code{\link{yml_runtime}()}, 71 | \code{\link{yml_site_opts}()}, 72 | \code{\link{yml_vignette}()} 73 | } 74 | \concept{yml} 75 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to ymlthis 2 | 3 | This outlines how to propose a change to ymlthis. For more detailed 4 | info about contributing to this, and other tidyverse packages, please see the 5 | [**development contributing guide**](https://rstd.io/tidy-contrib). 6 | 7 | ### Fixing typos 8 | 9 | Small typos or grammatical errors in documentation may be edited directly using 10 | the GitHub web interface, so long as the changes are made in the _source_ file. 11 | 12 | * YES: you edit a roxygen comment in a `.R` file below `R/`. 13 | * NO: you edit an `.Rd` file below `man/`. 14 | 15 | ### Prerequisites 16 | 17 | Before you make a substantial pull request, you should always file an issue and 18 | make sure someone from the team agrees that it’s a problem. If you’ve found a 19 | bug, create an associated issue and illustrate the bug with a minimal 20 | [reprex](https://www.tidyverse.org/help/#reprex). 21 | 22 | ### Pull request process 23 | 24 | * We recommend that you create a Git branch for each pull request (PR). 25 | * Look at the Travis and AppVeyor build status before and after making changes. 26 | The `README` should contain badges for any continuous integration services used 27 | by the package. 28 | * New code should follow the tidyverse [style guide](http://style.tidyverse.org). 29 | You can use the [styler](https://CRAN.R-project.org/package=styler) package to 30 | apply these styles, but please don't restyle code that has nothing to do with 31 | your PR. 32 | * We use [roxygen2](https://cran.r-project.org/package=roxygen2), with 33 | [Markdown syntax](https://cran.r-project.org/web/packages/roxygen2/vignettes/markdown.html), 34 | for documentation. 35 | * We use [testthat](https://cran.r-project.org/package=testthat). Contributions 36 | with test cases included are easier to accept. 37 | * For user-facing changes, add a bullet to the top of `NEWS.md` below the 38 | current development version header describing the changes made followed by your 39 | GitHub username, and links to relevant issue(s)/PR(s). 40 | 41 | ### Code of Conduct 42 | 43 | Please note that the ymlthis project is released with a 44 | [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this 45 | project you agree to abide by its terms. 46 | 47 | ### See tidyverse [development contributing guide](https://rstd.io/tidy-contrib) 48 | for further details. 49 | -------------------------------------------------------------------------------- /README.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | output: github_document 3 | --- 4 | 5 | 6 | 7 | ```{r, include = FALSE} 8 | knitr::opts_chunk$set( 9 | collapse = TRUE, 10 | comment = "#>", 11 | fig.path = "man/figures/README-", 12 | out.width = "100%" 13 | ) 14 | ``` 15 | # ymlthis: write YAML for R Markdown, bookdown, blogdown, and more 16 | 17 | 18 | [![R-CMD-check](https://github.com/r-lib/ymlthis/workflows/R-CMD-check/badge.svg)](https://github.com/r-lib/ymlthis/actions) 19 | [![Codecov test coverage](https://codecov.io/gh/r-lib/ymlthis/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/ymlthis?branch=main) 20 | [![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html) 21 | [![CRAN status](https://www.r-pkg.org/badges/version/ymlthis)](https://cran.r-project.org/package=ymlthis) 22 | 23 | 24 | ymlthis makes it easy to write YAML front matter for R Markdown and related documents. `yml_*()` functions write functions and `use_*()` functions let you write the resulting YAML to your clipboard or to `.yml` files related to your project. 25 | 26 | ## Installation 27 | 28 | You can install ymlthis from CRAN with: 29 | 30 | ``` r 31 | install.packages("ymlthis") 32 | ``` 33 | 34 | Or you can install the development version of ymlthis from GitHub with: 35 | 36 | ``` r 37 | # install.packages("remotes") 38 | remotes::install_github("r-lib/ymlthis") 39 | ``` 40 | 41 | ## Example 42 | 43 | `yml()` creates a basic `yml` object returns simple YAML with the author and date. 44 | 45 | ```{r example} 46 | library(ymlthis) 47 | 48 | yml() 49 | ``` 50 | 51 | ymlthis supports many YAML arguments, with YAML-generating functions prefixed with `yml_*()`: 52 | 53 | ```{r example-2, warning=FALSE} 54 | yml() %>% 55 | yml_author(c("Yihui Xie", "Hadley Wickham"), affiliation = "RStudio") %>% 56 | yml_date(lubridate::today()) %>% 57 | yml_output( 58 | word_document(keep_md = TRUE), 59 | bookdown::html_document2() 60 | ) %>% 61 | yml_citations(bibliography = "references.bib", csl = "aje.csl") 62 | ``` 63 | 64 | ## Add-in 65 | 66 | ymlthis also includes an add-in that will create YAML for you and put it in a file, such as an `.Rmd` file, or on your clipboard. 67 | 68 | ![](https://i.imgur.com/BkzGueG.gif) 69 | -------------------------------------------------------------------------------- /man/yml_runtime.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_rmarkdown.R 3 | \name{yml_runtime} 4 | \alias{yml_runtime} 5 | \title{Activate Shiny in R Markdown} 6 | \usage{ 7 | yml_runtime(.yml, runtime = c("static", "shiny", "shiny_prerendered")) 8 | } 9 | \arguments{ 10 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 11 | a \verb{yml_*()} function} 12 | 13 | \item{runtime}{The runtime target for rendering. \code{static}, the default, 14 | renders static documents; \code{shiny} allows you to include use Shiny in your 15 | document. \code{shiny_prerendered} is a subset of the \code{shiny} runtime that 16 | allows pre-rendering of app components (see the \href{https://rmarkdown.rstudio.com/authoring_shiny_prerendered.html}{R Markdown site} for 17 | more)} 18 | } 19 | \value{ 20 | a \code{yml} object 21 | } 22 | \description{ 23 | The \code{runtime} field lets you use Shiny in your R Markdown document, making it 24 | interactive. See the \href{https://bookdown.org/yihui/rmarkdown/interactive-documents.html}{R Markdown book} for 25 | examples. 26 | } 27 | \examples{ 28 | 29 | yml() \%>\% 30 | yml_runtime("shiny") 31 | 32 | } 33 | \seealso{ 34 | Other yml: 35 | \code{\link{asis_yaml_output}()}, 36 | \code{\link{bib2yml}()}, 37 | \code{\link{draw_yml_tree}()}, 38 | \code{\link{has_field}()}, 39 | \code{\link{read_json}()}, 40 | \code{\link{use_yml_defaults}()}, 41 | \code{\link{use_yml_file}()}, 42 | \code{\link{use_yml}()}, 43 | \code{\link{yml_author}()}, 44 | \code{\link{yml_blogdown_opts}()}, 45 | \code{\link{yml_bookdown_opts}()}, 46 | \code{\link{yml_citations}()}, 47 | \code{\link{yml_clean}()}, 48 | \code{\link{yml_distill_opts}()}, 49 | \code{\link{yml_latex_opts}()}, 50 | \code{\link{yml_output}()}, 51 | \code{\link{yml_pagedown_opts}()}, 52 | \code{\link{yml_params}()}, 53 | \code{\link{yml_pkgdown}()}, 54 | \code{\link{yml_reference}()}, 55 | \code{\link{yml_replace}()}, 56 | \code{\link{yml_resource_files}()}, 57 | \code{\link{yml_rsconnect_email}()}, 58 | \code{\link{yml_rticles_opts}()}, 59 | \code{\link{yml_site_opts}()}, 60 | \code{\link{yml_toc}()}, 61 | \code{\link{yml_vignette}()} 62 | 63 | Other R Markdown: 64 | \code{\link{yml_clean}()}, 65 | \code{\link{yml_params}()}, 66 | \code{\link{yml_site_opts}()}, 67 | \code{\link{yml_vignette}()} 68 | 69 | Other shiny: 70 | \code{\link{yml_params}()} 71 | } 72 | \concept{R Markdown} 73 | \concept{shiny} 74 | \concept{yml} 75 | -------------------------------------------------------------------------------- /man/use_yml_defaults.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/use_yml.R 3 | \name{use_yml_defaults} 4 | \alias{use_yml_defaults} 5 | \alias{use_rmd_defaults} 6 | \alias{get_yml_defaults} 7 | \alias{get_rmd_defaults} 8 | \title{Set up default YAML} 9 | \usage{ 10 | use_yml_defaults(.yml) 11 | 12 | use_rmd_defaults(x) 13 | 14 | get_yml_defaults() 15 | 16 | get_rmd_defaults() 17 | } 18 | \arguments{ 19 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 20 | a \verb{yml_*()} function} 21 | 22 | \item{x}{a character vector to use as the body text in \code{\link[=use_rmarkdown]{use_rmarkdown()}}.} 23 | } 24 | \description{ 25 | \code{use_yml_defaults()} takes a \code{yml} object and places code on the clipboard 26 | that will save the resulting YAML as the default for \code{yml()}. The code that 27 | is placed on the clipboard is raw YAML passed to \code{ymlthis.default_yml} via 28 | \code{options()}. Saving this code to your \code{.Rprofile} (see 29 | \code{\link[usethis:edit]{usethis::edit_r_profile()}})) will allow \code{\link[=yml]{yml()}} or 30 | \code{\link[=get_yml_defaults]{get_yml_defaults()}} to return the saved YAML. \code{use_rmd_defaults()} does 31 | the same for \code{ymlthis.rmd_body}, which is used in \code{\link[=use_rmarkdown]{use_rmarkdown()}} as the 32 | body text of the created R Markdown file. 33 | } 34 | \seealso{ 35 | \code{\link[=yml]{yml()}} \code{\link[=get_yml_defaults]{get_yml_defaults()}} 36 | 37 | Other yml: 38 | \code{\link{asis_yaml_output}()}, 39 | \code{\link{bib2yml}()}, 40 | \code{\link{draw_yml_tree}()}, 41 | \code{\link{has_field}()}, 42 | \code{\link{read_json}()}, 43 | \code{\link{use_yml_file}()}, 44 | \code{\link{use_yml}()}, 45 | \code{\link{yml_author}()}, 46 | \code{\link{yml_blogdown_opts}()}, 47 | \code{\link{yml_bookdown_opts}()}, 48 | \code{\link{yml_citations}()}, 49 | \code{\link{yml_clean}()}, 50 | \code{\link{yml_distill_opts}()}, 51 | \code{\link{yml_latex_opts}()}, 52 | \code{\link{yml_output}()}, 53 | \code{\link{yml_pagedown_opts}()}, 54 | \code{\link{yml_params}()}, 55 | \code{\link{yml_pkgdown}()}, 56 | \code{\link{yml_reference}()}, 57 | \code{\link{yml_replace}()}, 58 | \code{\link{yml_resource_files}()}, 59 | \code{\link{yml_rsconnect_email}()}, 60 | \code{\link{yml_rticles_opts}()}, 61 | \code{\link{yml_runtime}()}, 62 | \code{\link{yml_site_opts}()}, 63 | \code{\link{yml_toc}()}, 64 | \code{\link{yml_vignette}()} 65 | } 66 | \concept{yml} 67 | -------------------------------------------------------------------------------- /man/yml_output.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_output.R 3 | \name{yml_output} 4 | \alias{yml_output} 5 | \title{Capture, validate, and write output YAML} 6 | \usage{ 7 | yml_output(.yml, ...) 8 | } 9 | \arguments{ 10 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 11 | a \verb{yml_*()} function} 12 | 13 | \item{...}{valid R code calling functions that return objects of class 14 | \code{rmarkdown_output_format}, such as the \verb{*_document()} functions in 15 | rmarkdown.} 16 | } 17 | \value{ 18 | a \code{yml} object 19 | } 20 | \description{ 21 | \code{yml_output()} writes valid YAML for the \code{output} field of R Markdown YAML. 22 | \code{yml_output()} captures the actual output functions, such as 23 | \code{pdf_document()}, and translates them to YAML. This function accepts multiple 24 | output formats (separated by commas) and validates each by evaluating the 25 | function internally. The YAML fields in under \code{output} come from arguments in 26 | their respective R functions. If you wanted to see the available fields in 27 | \code{pdf_document()}, for instance, you would read the documentation for that 28 | function using \code{?pdf_document}. 29 | } 30 | \examples{ 31 | \donttest{ 32 | yml() \%>\% 33 | yml_output(html_document()) 34 | 35 | yml() \%>\% 36 | yml_output( 37 | pdf_document(keep_tex = TRUE, includes = includes2(after_body = "footer.tex")), 38 | bookdown::html_document2() 39 | ) 40 | } 41 | } 42 | \seealso{ 43 | Other yml: 44 | \code{\link{asis_yaml_output}()}, 45 | \code{\link{bib2yml}()}, 46 | \code{\link{draw_yml_tree}()}, 47 | \code{\link{has_field}()}, 48 | \code{\link{read_json}()}, 49 | \code{\link{use_yml_defaults}()}, 50 | \code{\link{use_yml_file}()}, 51 | \code{\link{use_yml}()}, 52 | \code{\link{yml_author}()}, 53 | \code{\link{yml_blogdown_opts}()}, 54 | \code{\link{yml_bookdown_opts}()}, 55 | \code{\link{yml_citations}()}, 56 | \code{\link{yml_clean}()}, 57 | \code{\link{yml_distill_opts}()}, 58 | \code{\link{yml_latex_opts}()}, 59 | \code{\link{yml_pagedown_opts}()}, 60 | \code{\link{yml_params}()}, 61 | \code{\link{yml_pkgdown}()}, 62 | \code{\link{yml_reference}()}, 63 | \code{\link{yml_replace}()}, 64 | \code{\link{yml_resource_files}()}, 65 | \code{\link{yml_rsconnect_email}()}, 66 | \code{\link{yml_rticles_opts}()}, 67 | \code{\link{yml_runtime}()}, 68 | \code{\link{yml_site_opts}()}, 69 | \code{\link{yml_toc}()}, 70 | \code{\link{yml_vignette}()} 71 | } 72 | \concept{yml} 73 | -------------------------------------------------------------------------------- /man/yml_vignette.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_rmarkdown.R 3 | \name{yml_vignette} 4 | \alias{yml_vignette} 5 | \title{Set up a package vignette} 6 | \usage{ 7 | yml_vignette(.yml, title, engine = "knitr::rmarkdown", encoding = "UTF-8") 8 | } 9 | \arguments{ 10 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 11 | a \verb{yml_*()} function} 12 | 13 | \item{title}{The title of the vignette} 14 | 15 | \item{engine}{The rendering engine for the vignette ("knitr::rmarkdown" by 16 | default)} 17 | 18 | \item{encoding}{The character encoding for the document ("UTF-8" by default).} 19 | } 20 | \value{ 21 | a \code{yml} object 22 | } 23 | \description{ 24 | To use an R Markdown file as a vignette, you need to specify an output format 25 | appropriate for inclusion in a package (for example, the lightweight 26 | \code{html_vignette()} output function included in rmarkdown) and to specify the 27 | \code{vignette} field, which specifies the title, engine, and encoding type of the 28 | vignette. See also \code{\link[usethis:use_vignette]{usethis::use_vignette()}} for setting up a package 29 | vignette. 30 | } 31 | \examples{ 32 | 33 | yml() \%>\% 34 | yml_output(html_vignette()) \%>\% 35 | yml_vignette("An introduction to R Markdown") 36 | 37 | } 38 | \seealso{ 39 | Other yml: 40 | \code{\link{asis_yaml_output}()}, 41 | \code{\link{bib2yml}()}, 42 | \code{\link{draw_yml_tree}()}, 43 | \code{\link{has_field}()}, 44 | \code{\link{read_json}()}, 45 | \code{\link{use_yml_defaults}()}, 46 | \code{\link{use_yml_file}()}, 47 | \code{\link{use_yml}()}, 48 | \code{\link{yml_author}()}, 49 | \code{\link{yml_blogdown_opts}()}, 50 | \code{\link{yml_bookdown_opts}()}, 51 | \code{\link{yml_citations}()}, 52 | \code{\link{yml_clean}()}, 53 | \code{\link{yml_distill_opts}()}, 54 | \code{\link{yml_latex_opts}()}, 55 | \code{\link{yml_output}()}, 56 | \code{\link{yml_pagedown_opts}()}, 57 | \code{\link{yml_params}()}, 58 | \code{\link{yml_pkgdown}()}, 59 | \code{\link{yml_reference}()}, 60 | \code{\link{yml_replace}()}, 61 | \code{\link{yml_resource_files}()}, 62 | \code{\link{yml_rsconnect_email}()}, 63 | \code{\link{yml_rticles_opts}()}, 64 | \code{\link{yml_runtime}()}, 65 | \code{\link{yml_site_opts}()}, 66 | \code{\link{yml_toc}()} 67 | 68 | Other R Markdown: 69 | \code{\link{yml_clean}()}, 70 | \code{\link{yml_params}()}, 71 | \code{\link{yml_runtime}()}, 72 | \code{\link{yml_site_opts}()} 73 | } 74 | \concept{R Markdown} 75 | \concept{yml} 76 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | # ymlthis: write YAML for R Markdown, bookdown, blogdown, and more 5 | 6 | 7 | 8 | [![R-CMD-check](https://github.com/r-lib/ymlthis/workflows/R-CMD-check/badge.svg)](https://github.com/r-lib/ymlthis/actions) 9 | [![Codecov test 10 | coverage](https://codecov.io/gh/r-lib/ymlthis/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/ymlthis?branch=main) 11 | [![Lifecycle: 12 | maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html) 13 | [![CRAN 14 | status](https://www.r-pkg.org/badges/version/ymlthis)](https://cran.r-project.org/package=ymlthis) 15 | 16 | 17 | ymlthis makes it easy to write YAML front matter for R Markdown and 18 | related documents. `yml_*()` functions write functions and `use_*()` 19 | functions let you write the resulting YAML to your clipboard or to 20 | `.yml` files related to your project. 21 | 22 | ## Installation 23 | 24 | You can install ymlthis from CRAN with: 25 | 26 | ``` r 27 | install.packages("ymlthis") 28 | ``` 29 | 30 | Or you can install the development version of ymlthis from GitHub with: 31 | 32 | ``` r 33 | # install.packages("remotes") 34 | remotes::install_github("r-lib/ymlthis") 35 | ``` 36 | 37 | ## Example 38 | 39 | `yml()` creates a basic `yml` object returns simple YAML with the author 40 | and date. 41 | 42 | ``` r 43 | library(ymlthis) 44 | 45 | yml() 46 | #> --- 47 | #> author: Malcolm Barrett 48 | #> date: '`r format(Sys.Date())`' 49 | #> --- 50 | ``` 51 | 52 | ymlthis supports many YAML arguments, with YAML-generating functions 53 | prefixed with `yml_*()`: 54 | 55 | ``` r 56 | yml() %>% 57 | yml_author(c("Yihui Xie", "Hadley Wickham"), affiliation = "RStudio") %>% 58 | yml_date(lubridate::today()) %>% 59 | yml_output( 60 | word_document(keep_md = TRUE), 61 | bookdown::html_document2() 62 | ) %>% 63 | yml_citations(bibliography = "references.bib", csl = "aje.csl") 64 | #> --- 65 | #> author: 66 | #> - name: Yihui Xie 67 | #> affiliation: RStudio 68 | #> - name: Hadley Wickham 69 | #> affiliation: RStudio 70 | #> date: '2022-06-24' 71 | #> output: 72 | #> word_document: 73 | #> keep_md: true 74 | #> bookdown::html_document2: default 75 | #> bibliography: references.bib 76 | #> csl: aje.csl 77 | #> --- 78 | ``` 79 | 80 | ## Add-in 81 | 82 | ymlthis also includes an add-in that will create YAML for you and put it 83 | in a file, such as an `.Rmd` file, or on your clipboard. 84 | 85 | ![](https://i.imgur.com/BkzGueG.gif) 86 | -------------------------------------------------------------------------------- /man/yml.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml.R 3 | \name{yml} 4 | \alias{yml} 5 | \alias{yml_empty} 6 | \title{Create a new yml object} 7 | \usage{ 8 | yml(.yml = NULL, get_yml = TRUE, author = TRUE, date = TRUE) 9 | 10 | yml_empty() 11 | } 12 | \arguments{ 13 | \item{.yml}{a character vector, \code{yml} object, or YAML-like list. See details.} 14 | 15 | \item{get_yml}{logical. Use YAML stored in 16 | \code{getOption("ymlthis.default_option")}? By default, \code{yml()} includes if it 17 | exists.} 18 | 19 | \item{author}{logical. Get default author name?} 20 | 21 | \item{date}{logical. Get default date?} 22 | } 23 | \value{ 24 | a \code{yml} object 25 | } 26 | \description{ 27 | \code{yml()} initializes a \code{yml} object. \code{yml} objects create valid YAML and print 28 | it cleanly to the console. By default, \code{yml()} looks for your name (using \code{ getOption("usethis.full_name")}, \code{getOption("devtools.name")}, and 29 | \code{whoami::fullname()}) and uses today's date to use in the \code{author} and \code{date} 30 | fields, respectively. If you've set default YAML in 31 | \code{getOption("ymlthis.default_option")} (see \code{\link[=use_yml_defaults]{use_yml_defaults()}}), \code{yml()} 32 | will also use include those fields by default. \code{yml_empty()} is a wrapper 33 | that doesn't use any of these default YAML fields. \code{yml()} and all 34 | related\verb{yml_*()} functions validate that the results are indeed valid YAML 35 | syntax, although not every function is able to check that the input fields 36 | are valid for the setting they are used in. 37 | } 38 | \details{ 39 | \code{.yml} accepts a character vector of YAML, such as "author: Hadley Wickham", 40 | an object returned by ymlthis functions that start with \verb{yml_*()}, or a 41 | \code{list} object (e.g. \code{list(author = "Hadley Wickham")}). \code{.yml} objects are 42 | processed with \code{\link[=as_yml]{as_yml()}}, a wrapper around \code{\link[yaml:yaml.load]{yaml::yaml.load()}}. See that 43 | function for more details. 44 | } 45 | \examples{ 46 | 47 | yml() 48 | 49 | yml(date = FALSE) 50 | 51 | "author: Hadley Wickham\ndate: 2014-09-12" \%>\% 52 | yml() \%>\% 53 | yml_title("Tidy Data") \%>\% 54 | yml_keywords( 55 | c("data cleaning", "data tidying", "relational databases", "R") 56 | ) 57 | \donttest{ 58 | yml() \%>\% 59 | yml_author( 60 | c("Yihui Xie", "Hadley Wickham"), 61 | affiliation = rep("RStudio", 2) 62 | ) \%>\% 63 | yml_date("07/04/2019") \%>\% 64 | yml_output( 65 | pdf_document( 66 | keep_tex = TRUE, 67 | includes = includes2(after_body = "footer.tex") 68 | ) 69 | ) \%>\% 70 | yml_latex_opts(biblio_style = "apalike") 71 | } 72 | } 73 | -------------------------------------------------------------------------------- /man/read_json.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/convert_metadata.R 3 | \name{read_json} 4 | \alias{read_json} 5 | \alias{read_toml} 6 | \alias{write_as_json} 7 | \alias{write_as_toml} 8 | \title{Read and write to JSON and TOML} 9 | \usage{ 10 | read_json(path) 11 | 12 | read_toml(path) 13 | 14 | write_as_json( 15 | .yml = NULL, 16 | path = NULL, 17 | out = NULL, 18 | build_ignore = FALSE, 19 | git_ignore = FALSE, 20 | quiet = FALSE 21 | ) 22 | 23 | write_as_toml( 24 | .yml = NULL, 25 | path = NULL, 26 | out = NULL, 27 | build_ignore = FALSE, 28 | git_ignore = FALSE, 29 | quiet = FALSE 30 | ) 31 | } 32 | \arguments{ 33 | \item{path}{a path to a JSON or TOML file} 34 | 35 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 36 | a \verb{yml_*()} function} 37 | 38 | \item{out}{The path to write out to. If \code{NULL}, will write to the \code{path} but 39 | change the file extension to \code{.toml} or \code{.json}.} 40 | 41 | \item{build_ignore}{Logical. Should the file be added to the \code{.Rbuildignore} 42 | file?} 43 | 44 | \item{git_ignore}{Logical. Should the file be added to the \code{.gitignore} file?} 45 | 46 | \item{quiet}{Logical. Whether to message about what is happening.} 47 | } 48 | \value{ 49 | a \code{yml} object (if reading) or the path (if writing) 50 | } 51 | \description{ 52 | Read JSON and TOML files in as \code{yml} objects with \verb{read_*()}. Write \code{yml} 53 | objects out as JSON and YAML files with \verb{write_as_*()}. You can also provide 54 | \verb{write_as_*()} a path to an existing \code{.yml} file to translate to JSON or 55 | TOML. These functions rely on Hugo and blogdown, so you must have blogdown 56 | installed. 57 | } 58 | \seealso{ 59 | Other yml: 60 | \code{\link{asis_yaml_output}()}, 61 | \code{\link{bib2yml}()}, 62 | \code{\link{draw_yml_tree}()}, 63 | \code{\link{has_field}()}, 64 | \code{\link{use_yml_defaults}()}, 65 | \code{\link{use_yml_file}()}, 66 | \code{\link{use_yml}()}, 67 | \code{\link{yml_author}()}, 68 | \code{\link{yml_blogdown_opts}()}, 69 | \code{\link{yml_bookdown_opts}()}, 70 | \code{\link{yml_citations}()}, 71 | \code{\link{yml_clean}()}, 72 | \code{\link{yml_distill_opts}()}, 73 | \code{\link{yml_latex_opts}()}, 74 | \code{\link{yml_output}()}, 75 | \code{\link{yml_pagedown_opts}()}, 76 | \code{\link{yml_params}()}, 77 | \code{\link{yml_pkgdown}()}, 78 | \code{\link{yml_reference}()}, 79 | \code{\link{yml_replace}()}, 80 | \code{\link{yml_resource_files}()}, 81 | \code{\link{yml_rsconnect_email}()}, 82 | \code{\link{yml_rticles_opts}()}, 83 | \code{\link{yml_runtime}()}, 84 | \code{\link{yml_site_opts}()}, 85 | \code{\link{yml_toc}()}, 86 | \code{\link{yml_vignette}()} 87 | } 88 | \concept{yml} 89 | -------------------------------------------------------------------------------- /man/yml_replace.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_replace.R 3 | \name{yml_replace} 4 | \alias{yml_replace} 5 | \alias{yml_discard} 6 | \alias{yml_pluck} 7 | \alias{yml_chuck} 8 | \title{Replace, pluck, or discard top-level YAML fields} 9 | \usage{ 10 | yml_replace(.yml, ...) 11 | 12 | yml_discard(.yml, .rid) 13 | 14 | yml_pluck(.yml, ...) 15 | 16 | yml_chuck(.yml, ...) 17 | } 18 | \arguments{ 19 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 20 | a \verb{yml_*()} function} 21 | 22 | \item{...}{additional named R objects, such as characters or lists, to 23 | transform into YAML} 24 | 25 | \item{.rid}{a character vector of fields to remove or a purrr-style lambda 26 | with a predicate (~ predicate) where fields that are \code{TRUE} will be 27 | discarded} 28 | } 29 | \value{ 30 | a \code{yml} object 31 | } 32 | \description{ 33 | \code{yml_replace()} replaces a named field with another value. As opposed to 34 | duplicating top-level fields with other functions, explicitly replacing them 35 | with \code{yml_replace()} will not raise a warning. \code{yml_discard()} removes values 36 | given either a character vector of names or a purrr-style lambda with a 37 | predicate (~ predicate); see the examples. \code{yml_pluck()} and \code{yml_chuck()} 38 | are wrappers around \code{\link[purrr:pluck]{purrr::pluck()}} and \code{\link[purrr:pluck]{purrr::chuck()}} that return \code{yml} 39 | objects. 40 | } 41 | \examples{ 42 | \donttest{ 43 | yml() \%>\% 44 | yml_clean(TRUE) \%>\% 45 | yml_replace(clean = FALSE) \%>\% 46 | yml_discard("author") 47 | 48 | yml() \%>\% 49 | yml_output( 50 | pdf_document(), 51 | html_document() 52 | )\%>\% 53 | yml_discard(~ length(.x) > 1) 54 | } 55 | 56 | } 57 | \seealso{ 58 | Other yml: 59 | \code{\link{asis_yaml_output}()}, 60 | \code{\link{bib2yml}()}, 61 | \code{\link{draw_yml_tree}()}, 62 | \code{\link{has_field}()}, 63 | \code{\link{read_json}()}, 64 | \code{\link{use_yml_defaults}()}, 65 | \code{\link{use_yml_file}()}, 66 | \code{\link{use_yml}()}, 67 | \code{\link{yml_author}()}, 68 | \code{\link{yml_blogdown_opts}()}, 69 | \code{\link{yml_bookdown_opts}()}, 70 | \code{\link{yml_citations}()}, 71 | \code{\link{yml_clean}()}, 72 | \code{\link{yml_distill_opts}()}, 73 | \code{\link{yml_latex_opts}()}, 74 | \code{\link{yml_output}()}, 75 | \code{\link{yml_pagedown_opts}()}, 76 | \code{\link{yml_params}()}, 77 | \code{\link{yml_pkgdown}()}, 78 | \code{\link{yml_reference}()}, 79 | \code{\link{yml_resource_files}()}, 80 | \code{\link{yml_rsconnect_email}()}, 81 | \code{\link{yml_rticles_opts}()}, 82 | \code{\link{yml_runtime}()}, 83 | \code{\link{yml_site_opts}()}, 84 | \code{\link{yml_toc}()}, 85 | \code{\link{yml_vignette}()} 86 | } 87 | \concept{yml} 88 | -------------------------------------------------------------------------------- /R/markdownr.R: -------------------------------------------------------------------------------- 1 | #' Write code chunks programmatically 2 | #' 3 | #' `code_chunk()` assembles a knitr code chunk as a character vector. 4 | #' `setup_chunk()` is a wrapper around `code_chunk()` to create setup chunks. By 5 | #' default it uses `include = FALSE` and inserts `knitr::opts_chunk$set(echo = 6 | #' TRUE)` into the chunk body. These are helper functions to write R Markdown 7 | #' bodies for [use_rmarkdown()]. 8 | #' 9 | #' @param chunk_code An expression. Surround with `{}` to capture multiple 10 | #' lines. 11 | #' @param chunk_name The name of the chunk 12 | #' @param chunk_args A `list` of chunk options 13 | #' 14 | #' @return a character vector 15 | #' @export 16 | #' 17 | #' @examples 18 | #' \donttest{ 19 | #'setup_chunk() 20 | #' 21 | #' code_chunk({ 22 | #' yml() %>% 23 | #' yml_output(pdf_document()) 24 | #' }, chunk_name = "yml_example") 25 | #' } 26 | code_chunk <- function(chunk_code, chunk_name = NULL, chunk_args = NULL) { 27 | chunk_args <- splice_args(rlang::enquo(chunk_args)) 28 | if (!is.null(chunk_name) && chunk_args != "") { 29 | chunk_name <- glue::glue("{chunk_name}, ") 30 | } 31 | 32 | chunk_code <- rlang::enexpr(chunk_code) %>% 33 | rlang::expr_text() %>% 34 | stringr::str_replace_all("^\\{\n|\\}$", "") %>% 35 | stringr::str_trim() %>% 36 | stringr::str_replace("\n$", "") %>% 37 | split_pluck() %>% 38 | stringr::str_replace("^\\s{4}", "") %>% 39 | glue::glue_collapse("\n") 40 | 41 | chunk_header <- paste0( 42 | "r", 43 | ifelse(is.null(chunk_name) && chunk_args == "", "", " "), 44 | chunk_name, 45 | chunk_args 46 | ) 47 | 48 | glue::glue( 49 | "```{<>}\n<>\n```", 50 | .open = "<<", 51 | .close = ">>" 52 | ) 53 | } 54 | 55 | #' @rdname code_chunk 56 | #' @export 57 | setup_chunk <- function(chunk_code = NULL, chunk_args = list(include = FALSE)) { 58 | arg_null <- rlang::enquo(chunk_code) %>% 59 | rlang::quo_is_null() 60 | 61 | if (arg_null) { 62 | code_chunk_txt <- code_chunk( 63 | chunk_code = {knitr::opts_chunk$set(echo = TRUE)}, 64 | chunk_name = "setup", 65 | chunk_args = !!rlang::enquo(chunk_args) 66 | ) 67 | } else { 68 | code_chunk_txt <- code_chunk( 69 | chunk_code = chunk_code, 70 | chunk_name = "setup", 71 | chunk_args = !!rlang::enquo(chunk_args) 72 | ) 73 | } 74 | 75 | code_chunk_txt 76 | } 77 | 78 | splice_args <- function(x) { 79 | # preserve calls without evaluating 80 | if (rlang::quo_is_null(x)) return("") 81 | args <- rlang::call_args(x) 82 | purrr::map2_chr(names(args), args, glue_args) %>% 83 | glue::glue_collapse(", ") 84 | } 85 | 86 | glue_args <- function(.x, .y) { 87 | if (is.character(.y)) { 88 | glue::glue("{.x} = \"{.y}\"") 89 | } else { 90 | glue::glue("{.x} = {.y}") 91 | } 92 | } 93 | -------------------------------------------------------------------------------- /man/yml_pagedown_opts.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_pagedown.R 3 | \name{yml_pagedown_opts} 4 | \alias{yml_pagedown_opts} 5 | \title{Top-level YAML options for pagedown} 6 | \usage{ 7 | yml_pagedown_opts( 8 | .yml, 9 | toc = yml_blank(), 10 | toc_title = yml_blank(), 11 | lot = yml_blank(), 12 | lot_title = yml_blank(), 13 | chapter_name = yml_blank(), 14 | links_to_footnotes = yml_blank(), 15 | paged_footnotes = yml_blank() 16 | ) 17 | } 18 | \arguments{ 19 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 20 | a \verb{yml_*()} function} 21 | 22 | \item{toc}{Logical. Use a table of contents?} 23 | 24 | \item{toc_title}{The title for the table of contents. Note that the actual 25 | YAML field is \code{toc-title}} 26 | 27 | \item{lot}{Logical. Use a list of figures?} 28 | 29 | \item{lot_title}{The title for the list of figures. Note that the actual YAML 30 | field is \code{lot-title}} 31 | 32 | \item{chapter_name}{The chapter title prefix} 33 | 34 | \item{links_to_footnotes}{Logical. Transform all the URLs to footnotes? Note 35 | that the actual YAML field is \code{links-to-footnotes}} 36 | 37 | \item{paged_footnotes}{Logical. Render notes as footnotes? Note that the 38 | actual YAML field is \code{paged-footnotes}} 39 | } 40 | \value{ 41 | a \code{yml} object 42 | } 43 | \description{ 44 | pagedown offers several output functions for paginated output, resumes, 45 | business cards, theses, and morem as described in the \href{https://pagedown.rbind.io/}{pagedown vignette}. pagedown also accepts a few custom 46 | top-level YAML. See \code{\link[=pagedown_business_card_template]{pagedown_business_card_template()}} for more on setting 47 | up the YAML for a business card. 48 | } 49 | \examples{ 50 | 51 | yml() \%>\% 52 | yml_pagedown_opts( 53 | toc = TRUE, 54 | toc_title = "TOC", 55 | chapter_name = c("CHAPTER\\\\ ", "."), 56 | links_to_footnotes = TRUE 57 | ) 58 | 59 | } 60 | \seealso{ 61 | Other yml: 62 | \code{\link{asis_yaml_output}()}, 63 | \code{\link{bib2yml}()}, 64 | \code{\link{draw_yml_tree}()}, 65 | \code{\link{has_field}()}, 66 | \code{\link{read_json}()}, 67 | \code{\link{use_yml_defaults}()}, 68 | \code{\link{use_yml_file}()}, 69 | \code{\link{use_yml}()}, 70 | \code{\link{yml_author}()}, 71 | \code{\link{yml_blogdown_opts}()}, 72 | \code{\link{yml_bookdown_opts}()}, 73 | \code{\link{yml_citations}()}, 74 | \code{\link{yml_clean}()}, 75 | \code{\link{yml_distill_opts}()}, 76 | \code{\link{yml_latex_opts}()}, 77 | \code{\link{yml_output}()}, 78 | \code{\link{yml_params}()}, 79 | \code{\link{yml_pkgdown}()}, 80 | \code{\link{yml_reference}()}, 81 | \code{\link{yml_replace}()}, 82 | \code{\link{yml_resource_files}()}, 83 | \code{\link{yml_rsconnect_email}()}, 84 | \code{\link{yml_rticles_opts}()}, 85 | \code{\link{yml_runtime}()}, 86 | \code{\link{yml_site_opts}()}, 87 | \code{\link{yml_toc}()}, 88 | \code{\link{yml_vignette}()} 89 | 90 | Other pagedown: 91 | \code{\link{pagedown_business_card_template}()} 92 | } 93 | \concept{pagedown} 94 | \concept{yml} 95 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | S3method(as_yml,character) 4 | S3method(as_yml,default) 5 | S3method(as_yml,list) 6 | S3method(as_yml,print_yaml) 7 | S3method(print,yml) 8 | export("%>%") 9 | export(as_yml) 10 | export(asis_yaml_output) 11 | export(bib2yml) 12 | export(blogdown_archetypes) 13 | export(blogdown_template) 14 | export(code_chunk) 15 | export(distill_collection) 16 | export(distill_listing) 17 | export(distill_resources) 18 | export(draw_yml_tree) 19 | export(get_rmd_defaults) 20 | export(get_yml_defaults) 21 | export(gitbook_config) 22 | export(has_field) 23 | export(includes2) 24 | export(is_yml) 25 | export(is_yml_blank) 26 | export(last_yml) 27 | export(navbar_page) 28 | export(navbar_separator) 29 | export(pagedown_business_card_template) 30 | export(pagedown_person) 31 | export(pandoc_highlight_styles) 32 | export(pandoc_template_types) 33 | export(pkgdown_article) 34 | export(pkgdown_ref) 35 | export(pkgdown_template) 36 | export(pkgdown_tutorial) 37 | export(read_json) 38 | export(read_toml) 39 | export(reference) 40 | export(rticles_address) 41 | export(rticles_author) 42 | export(rticles_corr_author) 43 | export(setup_chunk) 44 | export(shiny_checkbox) 45 | export(shiny_date) 46 | export(shiny_file) 47 | export(shiny_numeric) 48 | export(shiny_params) 49 | export(shiny_password) 50 | export(shiny_radio) 51 | export(shiny_select) 52 | export(shiny_slider) 53 | export(shiny_text) 54 | export(use_bookdown_yml) 55 | export(use_index_rmd) 56 | export(use_navbar_yml) 57 | export(use_output_yml) 58 | export(use_pandoc_highlight_style) 59 | export(use_pandoc_template) 60 | export(use_pkgdown_yml) 61 | export(use_rmarkdown) 62 | export(use_rmd_defaults) 63 | export(use_site_yml) 64 | export(use_yml) 65 | export(use_yml_defaults) 66 | export(use_yml_file) 67 | export(write_as_json) 68 | export(write_as_toml) 69 | export(yml) 70 | export(yml_abstract) 71 | export(yml_author) 72 | export(yml_blank) 73 | export(yml_blogdown_opts) 74 | export(yml_bookdown_opts) 75 | export(yml_bookdown_site) 76 | export(yml_category) 77 | export(yml_chuck) 78 | export(yml_citations) 79 | export(yml_clean) 80 | export(yml_code) 81 | export(yml_date) 82 | export(yml_description) 83 | export(yml_discard) 84 | export(yml_distill_author) 85 | export(yml_distill_opts) 86 | export(yml_empty) 87 | export(yml_handlers) 88 | export(yml_keywords) 89 | export(yml_lang) 90 | export(yml_latex_opts) 91 | export(yml_load) 92 | export(yml_navbar) 93 | export(yml_output) 94 | export(yml_output_metadata) 95 | export(yml_pagedown_opts) 96 | export(yml_params) 97 | export(yml_params_code) 98 | export(yml_pkgdown) 99 | export(yml_pkgdown_articles) 100 | export(yml_pkgdown_development) 101 | export(yml_pkgdown_docsearch) 102 | export(yml_pkgdown_figures) 103 | export(yml_pkgdown_news) 104 | export(yml_pkgdown_opts) 105 | export(yml_pkgdown_reference) 106 | export(yml_pkgdown_template) 107 | export(yml_pkgdown_tutorial) 108 | export(yml_pluck) 109 | export(yml_reference) 110 | export(yml_replace) 111 | export(yml_resource_files) 112 | export(yml_rsconnect_email) 113 | export(yml_rticles_opts) 114 | export(yml_runtime) 115 | export(yml_site_opts) 116 | export(yml_subject) 117 | export(yml_subtitle) 118 | export(yml_title) 119 | export(yml_toc) 120 | export(yml_toplevel) 121 | export(yml_verbatim) 122 | export(yml_vignette) 123 | importFrom(magrittr,"%>%") 124 | importFrom(utils,getFromNamespace) 125 | -------------------------------------------------------------------------------- /R/use_pandoc.R: -------------------------------------------------------------------------------- 1 | #' Use pandoc templates and custom highlight themes 2 | #' 3 | #' Pandoc has several built in templates and code highlighting themes that can 4 | #' be customized and included in the `template` and `highlight-style` YAML 5 | #' fields, respectively. `pandoc_template_types()` and 6 | #' `pandoc_highlight_styles()` return the available templates and highlight 7 | #' styles in pandoc, respectively. `use_pandoc_template()` creates a new file 8 | #' based on a template from pandoc or R Markdown and 9 | #' `use_pandoc_highlight_style()` creates a new highlight theme file based on an 10 | #' existing pandoc theme. 11 | #' 12 | #' @param theme The name of the theme 13 | #' @param type The template type 14 | #' @param source The template source ("pandoc" or "rmarkdown") 15 | #' @param path The path to write the file to 16 | #' 17 | #' @return a character vector 18 | #' @export 19 | pandoc_template_types <- function() { 20 | c( 21 | "asciidoc", 22 | "asciidoctor", 23 | "commonmark", 24 | "context", 25 | "docbook4", 26 | "docbook5", 27 | "dokuwiki", 28 | "dzslides", 29 | "epub2", 30 | "epub3", 31 | "haddock", 32 | "html4", 33 | "html5", 34 | "icml", 35 | "jats", 36 | "jira", 37 | "latex", 38 | "latex.orig", 39 | "latex.rej", 40 | "man", 41 | "markdown", 42 | "mediawiki", 43 | "ms", 44 | "muse", 45 | "opendocument", 46 | "opml", 47 | "org", 48 | "plain", 49 | "revealjs", 50 | "rst", 51 | "rtf", 52 | "s5", 53 | "slideous", 54 | "slidy", 55 | "tei", 56 | "texinfo", 57 | "textile", 58 | "xwiki", 59 | "zimwiki" 60 | ) 61 | } 62 | 63 | #' @export 64 | #' @rdname pandoc_template_types 65 | pandoc_highlight_styles <- function() { 66 | stop_if_pandoc_not_installed() 67 | system2(rmarkdown::pandoc_exec(), "--list-highlight-styles", stdout = TRUE) 68 | } 69 | 70 | 71 | #' @export 72 | #' @rdname pandoc_template_types 73 | use_pandoc_template <- function(type, path, source = c("rmarkdown", "pandoc")) { 74 | stop_if_pandoc_not_installed() 75 | source <- match.arg(source) 76 | 77 | if (source == "rmarkdown") { 78 | x <- switch( 79 | type, 80 | latex = read_file("latex", "default.tex"), 81 | html = read_file("h", "default.html"), 82 | slidy = read_file("slidy", "default.html"), 83 | ioslides = read_file("ioslides", "default.html"), 84 | html_fragment = read_file("fragment", "default.html"), 85 | latex_fragment = read_file("fragment", "default.tex"), 86 | ) 87 | } 88 | 89 | if (source == "pandoc") { 90 | args <- glue::glue("--print-default-template={type}") 91 | x <- system2(rmarkdown::pandoc_exec(), args = args, stdout = TRUE) 92 | } 93 | 94 | usethis::write_over(path, x) 95 | } 96 | 97 | 98 | read_file <- function(...) { 99 | readLines( 100 | system.file( 101 | "rmd", 102 | ..., 103 | package = "rmarkdown", 104 | mustWork = TRUE 105 | ) 106 | ) 107 | } 108 | 109 | 110 | #' @export 111 | #' @rdname pandoc_template_types 112 | use_pandoc_highlight_style <- function(theme, path) { 113 | stop_if_pandoc_not_installed() 114 | if (!grepl("\\.theme$", path)) { 115 | stop("`path` must end in `.theme`", call. = FALSE) 116 | } 117 | 118 | args <- glue::glue("--print-highlight-style={theme}") 119 | x <- system2(rmarkdown::pandoc_exec(), args = args, stdout = TRUE) 120 | 121 | usethis::write_over(path, x) 122 | } 123 | 124 | stop_if_pandoc_not_installed <- function() { 125 | stop_if_rmarkdown_not_installed() 126 | if (!rmarkdown::pandoc_available()) { 127 | stop("pandoc must be installed to use this function") 128 | } 129 | } 130 | 131 | -------------------------------------------------------------------------------- /R/yml_output.R: -------------------------------------------------------------------------------- 1 | #' Capture, validate, and write output YAML 2 | #' 3 | #' `yml_output()` writes valid YAML for the `output` field of R Markdown YAML. 4 | #' `yml_output()` captures the actual output functions, such as 5 | #' `pdf_document()`, and translates them to YAML. This function accepts multiple 6 | #' output formats (separated by commas) and validates each by evaluating the 7 | #' function internally. The YAML fields in under `output` come from arguments in 8 | #' their respective R functions. If you wanted to see the available fields in 9 | #' `pdf_document()`, for instance, you would read the documentation for that 10 | #' function using `?pdf_document`. 11 | #' 12 | #' @template describe_yml_param 13 | #' @param ... valid R code calling functions that return objects of class 14 | #' `rmarkdown_output_format`, such as the `*_document()` functions in 15 | #' rmarkdown. 16 | #' 17 | #' @template describe_yml_output 18 | #' @export 19 | #' 20 | #' @examples 21 | #'\donttest{ 22 | #' yml() %>% 23 | #' yml_output(html_document()) 24 | #' 25 | #' yml() %>% 26 | #' yml_output( 27 | #' pdf_document(keep_tex = TRUE, includes = includes2(after_body = "footer.tex")), 28 | #' bookdown::html_document2() 29 | #' ) 30 | #'} 31 | yml_output <- function(.yml, ...) { 32 | x <- rlang::enquos(...) 33 | validate_output_yml(x) 34 | 35 | args_list <- purrr::map(x, rlang::call_args) 36 | function_name_list <- purrr::map(x, rlang::call_name) 37 | 38 | # add namespaces to functions when used 39 | function_namespaces <- purrr::map(x, rlang::call_ns) 40 | function_name_list <- purrr::map2( 41 | function_namespaces, 42 | function_name_list, 43 | prepend_namespace 44 | ) 45 | 46 | 47 | if (length(x) == 1) { 48 | .yml$output <- parse_output_yml(args_list[[1]], function_name_list[[1]]) 49 | return(.yml) 50 | } 51 | 52 | warn_if_duplicate_fields(.yml, list(output = "")) 53 | .yml$output <- purrr::map2( 54 | args_list, 55 | function_name_list, 56 | parse_output_yml, 57 | use_default = TRUE 58 | ) %>% 59 | purrr::flatten() 60 | 61 | .yml 62 | } 63 | 64 | eval_with_rmarkdown <- function(x, check_type = TRUE) { 65 | msg <- "rmarkdown must be installed to use outputs" 66 | if (!requireNamespace("rmarkdown", quietly = TRUE)) stop(msg, call. = FALSE) 67 | x <- withr::with_namespace( 68 | "rmarkdown", 69 | rlang::eval_tidy(x) 70 | ) 71 | 72 | if (check_type && !inherits(x, "rmarkdown_output_format")) { 73 | stop( 74 | "`output` must return object of class `rmarkdown_output_format`", 75 | call. = FALSE 76 | ) 77 | } 78 | 79 | x 80 | } 81 | 82 | parse_output_yml <- function(args, function_name, use_default = FALSE) { 83 | if (!rlang::has_length(args) && !use_default) { 84 | return(function_name) 85 | } 86 | 87 | if (!rlang::has_length(args) && use_default) { 88 | output_yml <- list("default") 89 | names(output_yml) <- function_name 90 | return(output_yml) 91 | } 92 | 93 | yml_list <- list( 94 | purrr::map_if(args, rlang::is_call, eval_with_rmarkdown, check_type = FALSE)) 95 | names(yml_list) <- function_name 96 | 97 | yml_list 98 | } 99 | 100 | stop_yml_eval <- function(e, x) { 101 | stop( 102 | "Invalid argument in YAML output function ", 103 | rlang::quo_text(x), 104 | "\n", 105 | as.character(e), 106 | call. = FALSE 107 | ) 108 | } 109 | 110 | eval_tidy_yml <- function(x) { 111 | out <- rlang::catch_cnd( 112 | eval_with_rmarkdown(x), 113 | classes = "error" 114 | ) 115 | 116 | if (!is.null(out)) stop_yml_eval(out, x) 117 | 118 | out 119 | } 120 | 121 | validate_output_yml <- function(.function_calls) { 122 | purrr::walk(.function_calls, eval_tidy_yml) 123 | } 124 | -------------------------------------------------------------------------------- /man/gitbook_config.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_bookdown.R 3 | \name{gitbook_config} 4 | \alias{gitbook_config} 5 | \title{Configure \code{bookdown::gitbook()} output} 6 | \usage{ 7 | gitbook_config( 8 | toc_collapse = yml_blank(), 9 | toc_scroll_highlight = yml_blank(), 10 | toc_before = yml_blank(), 11 | toc_after = yml_blank(), 12 | toolbar_position = yml_blank(), 13 | edit = yml_blank(), 14 | download = yml_blank(), 15 | search = yml_blank(), 16 | fontsettings_theme = yml_blank(), 17 | fontsettings_family = yml_blank(), 18 | fontsettings_size = yml_blank(), 19 | sharing_facebook = yml_blank(), 20 | sharing_twitter = yml_blank(), 21 | sharing_google = yml_blank(), 22 | sharing_linkedin = yml_blank(), 23 | sharing_weibo = yml_blank(), 24 | sharing_instapaper = yml_blank(), 25 | sharing_vk = yml_blank(), 26 | sharing_all = yml_blank(), 27 | ... 28 | ) 29 | } 30 | \arguments{ 31 | \item{toc_collapse}{Collapse some items initially when a page is loaded via 32 | the collapse option. Its possible values are "subsection" (the default), 33 | "section", "none", or \code{NULL}.} 34 | 35 | \item{toc_scroll_highlight}{Logical. Enable highlighting of TOC items as you 36 | scroll the book body? The default is \code{TRUE}.} 37 | 38 | \item{toc_before, toc_after}{a character vector of HTML to add more items 39 | before and after the TOC using the HTML tag \verb{
  • }. These items will be 40 | separated from the TOC using a horizontal divider.} 41 | 42 | \item{toolbar_position}{The toolbar position: "fixed" or "static." The 43 | default ("fixed") is that the toolbar will be fixed at the top of the page, 44 | whereas when set to "static" the toolbar will not scroll with the page.} 45 | 46 | \item{edit}{If not empty, an edit button will be added to the toolbar.} 47 | 48 | \item{download}{This option takes either a character vector or a list of 49 | character vectors with the length of each vector being 2. When it is a 50 | character vector, it should be either a vector of filenames or filename 51 | extensions. When you only provide the filename extensions, the filename is 52 | derived from the book filename of the configuration file \verb{_bookdown.yml}} 53 | 54 | \item{search}{Include a search bar?} 55 | 56 | \item{fontsettings_theme}{The theme. "White" (the default), "Sepia", or 57 | "Night".} 58 | 59 | \item{fontsettings_family}{The font family. "sans" (the default) or "serif".} 60 | 61 | \item{fontsettings_size}{The font size. Default is 2.} 62 | 63 | \item{sharing_facebook}{Logical. Include Facebook share link? Default is 64 | \code{TRUE}.} 65 | 66 | \item{sharing_twitter}{Logical. Include Twitter share link? Default is 67 | \code{TRUE}.} 68 | 69 | \item{sharing_google}{Logical. Include Google share link? Default is \code{FALSE}.} 70 | 71 | \item{sharing_linkedin}{Logical. Include LinkedIn share link? Default is 72 | \code{FALSE}.} 73 | 74 | \item{sharing_weibo}{Logical. Include Weibo share link? Default is \code{FALSE}.} 75 | 76 | \item{sharing_instapaper}{Logical. Include Instapaper share link? Default is 77 | \code{FALSE}.} 78 | 79 | \item{sharing_vk}{Logical. Include VK share link? Default is \code{FALSE}.} 80 | 81 | \item{sharing_all}{Logical. Include all share links? Default is \code{FALSE}.} 82 | 83 | \item{...}{additional named R objects, such as characters or lists, to 84 | transform into YAML} 85 | } 86 | \value{ 87 | a list to use in the \code{config} argument of \code{\link[bookdown:gitbook]{bookdown::gitbook()}} 88 | } 89 | \description{ 90 | \code{gitbook_config()} is a helper function to specify the \code{config} argument in 91 | \code{\link[bookdown:gitbook]{bookdown::gitbook()}}, as described in the \href{https://bookdown.org/yihui/bookdown/html.html}{bookdown book}. 92 | } 93 | \seealso{ 94 | Other bookdown: 95 | \code{\link{yml_bookdown_opts}()} 96 | } 97 | \concept{bookdown} 98 | -------------------------------------------------------------------------------- /R/utils.R: -------------------------------------------------------------------------------- 1 | stop_if_not_installed <- function(pkg) { 2 | rlang::check_installed(pkg, "Must be installed to use this function.") 3 | } 4 | 5 | stop_if_shiny_not_installed <- function() { 6 | stop_if_not_installed("shiny") 7 | } 8 | 9 | stop_if_rmarkdown_not_installed <- function() { 10 | stop_if_not_installed("rmarkdown") 11 | } 12 | 13 | stop_if_blogdown_not_installed <- function() { 14 | stop_if_not_installed("blogdown") 15 | } 16 | 17 | stop_if_not_type <- function(x, type) { 18 | if (is_yml_blank(x)) return(invisible(x)) 19 | if (!inherits(x, type)) { 20 | x_text <- rlang::quo_text(rlang::quo(x)) 21 | stop_must_be_type(x_text, type) 22 | } 23 | 24 | invisible(x) 25 | } 26 | 27 | stop_if_not_all_type <- function(x, type) { 28 | x_text <- rlang::quo_text(rlang::quo(x)) 29 | all_type <- all(purrr::map_lgl(x, inherits, type)) 30 | if (!all_type) { 31 | x_text <- rlang::quo_text(rlang::quo(x)) 32 | stop_must_be_type(x_text, type) 33 | } 34 | } 35 | 36 | stop_must_be_type <- function(x, type) { 37 | usethis::ui_stop( 38 | "{usethis::ui_code(x)} must be of type {usethis::ui_code(type)}" 39 | ) 40 | } 41 | 42 | warn_if_duplicate_fields <- function(yml_object, new_fields) { 43 | fields <- names(new_fields) 44 | duplicate_fields <- any(names(yml_object) %in% fields) 45 | 46 | if (duplicate_fields) { 47 | fields <- glue::glue("`{fields}`") %>% 48 | glue::glue_collapse(sep = ", ", last = " and ") 49 | msg <- glue::glue( 50 | "Top-level fields {fields} already present. \\ 51 | Replacing the existing fields. \\ 52 | Use `yml_replace() if you want to replace fields without a warning." 53 | ) 54 | warning(msg, call. = FALSE) 55 | } 56 | 57 | invisible(yml_object) 58 | } 59 | 60 | capture_yml <- function(.yml) { 61 | withr::local_envvar(NO_COLOR = TRUE) 62 | utils::capture.output(print(.yml)) 63 | } 64 | 65 | split_pluck <- function(string) { 66 | x <- stringr::str_split(string, "\n") 67 | x[[1]] 68 | } 69 | 70 | prepend_namespace <- function(function_namespace, function_name) { 71 | ifelse( 72 | is.null(function_namespace), 73 | function_name, 74 | paste0(function_namespace, "::", function_name) 75 | ) 76 | } 77 | 78 | `%nin%` <- Negate("%in%") 79 | 80 | # These are derived from https://github.com/r-lib/cli/blob/e9acc82b0d20fa5c64dd529400b622c0338374ed/R/tree.R#L111 81 | box_chars <- function(.subset = NULL) { 82 | if (is_utf8_output()) { 83 | x <- list( 84 | "h" = "\u2500", # horizontal 85 | "v" = "\u2502", # vertical 86 | "l" = "\u2514", 87 | "j" = "\u251C" 88 | ) 89 | } else { 90 | x <- list( 91 | "h" = "-", # horizontal 92 | "v" = "|", # vertical 93 | "l" = "\\", 94 | "j" = "+" 95 | ) 96 | } 97 | 98 | if (!is.null(.subset)) { 99 | return(x[[.subset]]) 100 | } 101 | 102 | x 103 | } 104 | 105 | is_latex_output <- function() { 106 | if (!("knitr" %in% loadedNamespaces())) return(FALSE) 107 | get("is_latex_output", asNamespace("knitr"))() 108 | } 109 | 110 | is_utf8_output <- function() { 111 | opt <- getOption("cli.unicode", NULL) 112 | if (!is.null(opt)) { 113 | isTRUE(opt) 114 | } else { 115 | l10n_info()$`UTF-8` && !is_latex_output() 116 | } 117 | } 118 | 119 | temporary_dir <- function() { 120 | tmp_dir_path <- file.path(tempdir(), "ymlthis_temp_dir__") 121 | if (!fs::dir_exists(tmp_dir_path)) { 122 | fs::dir_create(tmp_dir_path) 123 | } 124 | 125 | tmp_dir_path 126 | } 127 | 128 | unlink_temporary_dir <- function() { 129 | tmp_dir_path <- file.path(tempdir(), "ymlthis_temp_dir__") 130 | unlink(tmp_dir_path, recursive = TRUE, force = TRUE) 131 | invisible(tmp_dir_path) 132 | } 133 | -------------------------------------------------------------------------------- /man/yml_citations.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_citations.R 3 | \name{yml_citations} 4 | \alias{yml_citations} 5 | \title{Set citation-related YAML options} 6 | \usage{ 7 | yml_citations( 8 | .yml, 9 | bibliography = yml_blank(), 10 | biblio_style = yml_blank(), 11 | biblio_title = yml_blank(), 12 | csl = yml_blank(), 13 | citation_abbreviations = yml_blank(), 14 | link_citations = yml_blank(), 15 | nocite = yml_blank(), 16 | suppress_bibliography = yml_blank() 17 | ) 18 | } 19 | \arguments{ 20 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 21 | a \verb{yml_*()} function} 22 | 23 | \item{bibliography}{a path to a bibliography file, such as a .bib file} 24 | 25 | \item{biblio_style}{bibliography style, when used with 26 | \href{https://ctan.org/pkg/natbib}{natbib} and 27 | \href{https://ctan.org/pkg/biblatex}{biblatex}. Note that the actual YAML field 28 | is \code{biblio-style}} 29 | 30 | \item{biblio_title}{bibliography title, when used with 31 | \href{https://ctan.org/pkg/natbib}{natbib} and 32 | \href{https://ctan.org/pkg/biblatex}{biblatex}. Note that the actual YAML field 33 | is \code{biblio-title}} 34 | 35 | \item{csl}{a path to a Citation Style Language (CSL) file. CSL files are used 36 | to specify the citation style; see the \href{https://github.com/citation-style-language/styles}{CSL repository} for the CSL 37 | files of dozens of journals.} 38 | 39 | \item{citation_abbreviations}{Path to a CSL abbreviations JSON file. See the 40 | \href{https://manpages.ubuntu.com/manpages/xenial/man1/pandoc-citeproc.1.html}{pandoc-citeproc documentation}. 41 | Note that the actual YAML field is \code{citation-abbreviations}.} 42 | 43 | \item{link_citations}{Logical. Add citations hyperlinks to the corresponding 44 | bibliography entries? Note that the actual YAML field is \code{link-citations}.} 45 | 46 | \item{nocite}{Citation IDs (\code{"@item1"}) to include in the bibliography even if 47 | they are not cited in the document. Including the wildcard pattern \code{"@*"} 48 | will include all citations in the bibliography regardless of if they're 49 | cited in the document.} 50 | 51 | \item{suppress_bibliography}{Logical. Suppress bibliography?} 52 | } 53 | \value{ 54 | a \code{yml} object 55 | } 56 | \description{ 57 | \code{yml_citations()} sets citation-related YAML fields, such as specifying a 58 | bibliography file or style. For controlling the citation engine in PDF 59 | documents, see the \code{citation_package} argument in 60 | \code{rmarkdown::pdf_document()}. 61 | } 62 | \examples{ 63 | 64 | yml() \%>\% 65 | yml_citations(bibliography = "references.bib", csl = "aje.csl") 66 | 67 | } 68 | \seealso{ 69 | Other yml: 70 | \code{\link{asis_yaml_output}()}, 71 | \code{\link{bib2yml}()}, 72 | \code{\link{draw_yml_tree}()}, 73 | \code{\link{has_field}()}, 74 | \code{\link{read_json}()}, 75 | \code{\link{use_yml_defaults}()}, 76 | \code{\link{use_yml_file}()}, 77 | \code{\link{use_yml}()}, 78 | \code{\link{yml_author}()}, 79 | \code{\link{yml_blogdown_opts}()}, 80 | \code{\link{yml_bookdown_opts}()}, 81 | \code{\link{yml_clean}()}, 82 | \code{\link{yml_distill_opts}()}, 83 | \code{\link{yml_latex_opts}()}, 84 | \code{\link{yml_output}()}, 85 | \code{\link{yml_pagedown_opts}()}, 86 | \code{\link{yml_params}()}, 87 | \code{\link{yml_pkgdown}()}, 88 | \code{\link{yml_reference}()}, 89 | \code{\link{yml_replace}()}, 90 | \code{\link{yml_resource_files}()}, 91 | \code{\link{yml_rsconnect_email}()}, 92 | \code{\link{yml_rticles_opts}()}, 93 | \code{\link{yml_runtime}()}, 94 | \code{\link{yml_site_opts}()}, 95 | \code{\link{yml_toc}()}, 96 | \code{\link{yml_vignette}()} 97 | 98 | Other citations: 99 | \code{\link{bib2yml}()}, 100 | \code{\link{yml_reference}()} 101 | } 102 | \concept{citations} 103 | \concept{yml} 104 | -------------------------------------------------------------------------------- /R/draw_tree.R: -------------------------------------------------------------------------------- 1 | #' Draw an tree of YAML hierarchy 2 | #' 3 | #' `draw_yml_tree()` draws an ASCII tree of the hierarchy of a given `yml` 4 | #' object to the console. 5 | #' 6 | #' @template describe_yml_param 7 | #' @param indent a character vector used to indent the tree 8 | #' 9 | #' @return invisibly, `.yml` 10 | #' @export 11 | #' 12 | #' @examples 13 | #' # draw the most recently used `yml` 14 | #' draw_yml_tree() 15 | #'\donttest{ 16 | #' yml() %>% 17 | #' yml_output( 18 | #' pdf_document(keep_tex = TRUE), 19 | #' html_document() 20 | #' ) %>% 21 | #' draw_yml_tree() 22 | #'} 23 | draw_yml_tree <- function(.yml = last_yml(), indent = "") { 24 | any_vectors <- any(purrr::map_lgl(.yml, is_long_vector)) 25 | if (any_vectors) { 26 | print_vector_leaves(.yml, indent) 27 | return(invisible(.yml)) 28 | } 29 | 30 | nested <- purrr::map_lgl(.yml, is.list) 31 | for (i in seq_along(.yml)) { 32 | if (i == length(.yml)) { 33 | if (nested[i]) { 34 | if (!rlang::is_named(.yml[i])) { 35 | print_vector_leaves(.yml[[i]], indent) 36 | next 37 | } 38 | 39 | if (is_long_vector(.yml[[i]])) { 40 | print_vector_leaves(.yml[[i]], indent) 41 | next 42 | } 43 | 44 | leaf <- .yml[i] %>% 45 | color_yml() %>% 46 | split_pluck() %>% 47 | purrr::pluck(1) 48 | 49 | cat(paste0(indent, end_tab(), leaf, "\n")) 50 | draw_yml_tree(.yml[[i]], paste0(indent, " ")) 51 | 52 | } else { 53 | leaf <- color_yml(.yml[i]) 54 | cat(paste0(indent, end_tab(), leaf)) 55 | } 56 | } else { 57 | if (nested[i]) { 58 | if (!rlang::is_named(.yml[i])) { 59 | print_vector_leaves(.yml[[i]], indent) 60 | next 61 | } 62 | 63 | if (is_long_vector(.yml[[i]])) { 64 | marker <- ifelse(i != length(.yml), pipe(), " ") 65 | print_vector_leaves(.yml[[i]], paste0(indent, marker, " ")) 66 | next 67 | } 68 | 69 | leaf <- .yml[i] %>% 70 | color_yml() %>% 71 | split_pluck() %>% 72 | purrr::pluck(1) 73 | 74 | cat(paste0(indent, tab(), leaf, "\n")) 75 | draw_yml_tree(.yml[[i]], paste0(indent, pipe(), " ")) 76 | } else { 77 | if (!rlang::is_named(.yml[i])) { 78 | print_vector_leaves(.yml[[i]], indent) 79 | next 80 | } 81 | 82 | if (is_long_vector(.yml[[i]])) { 83 | return(invisible(.yml)) 84 | } 85 | 86 | leaf <- color_yml(.yml[i]) 87 | leaf_indent <- paste0(indent, tab()) 88 | cat(paste0(leaf_indent, leaf)) 89 | } 90 | } 91 | } 92 | 93 | invisible(.yml) 94 | } 95 | 96 | is_long_vector <- function(x) { 97 | is.atomic(x) && length(x) > 1 98 | } 99 | 100 | print_vector_leaves <- function(x, indent) { 101 | if (is.atomic(x)) { 102 | leaf <- color_yml(x) %>% 103 | split_pluck() 104 | } else { 105 | leaf <- vector("character", length(x)) 106 | for (i in seq_along(x)) { 107 | leaf[i] <- color_yml(x[i]) %>% 108 | split_pluck() %>% 109 | purrr::pluck(1) 110 | } 111 | 112 | } 113 | 114 | for (i in seq_along(x)) { 115 | if (i == length(x)) { 116 | cat(paste0(indent, end_tab(), leaf[i], "\n")) 117 | } else { 118 | cat(paste0(indent, tab(), leaf[i], "\n")) 119 | } 120 | if (is_long_vector(x[[i]])) { 121 | marker <- ifelse(i != length(x), pipe(), " ") 122 | print_vector_leaves(x[[i]], paste0(indent, marker, " ")) 123 | } 124 | 125 | if (is.list(x[[i]])) { 126 | marker <- ifelse(i != length(x), pipe(), " ") 127 | draw_yml_tree(x[[i]], paste0(indent, marker, " ")) 128 | } 129 | } 130 | } 131 | 132 | pipe <- function() box_chars("v") 133 | tab <- function() paste0(box_chars("j"), box_chars("h"), box_chars("h"), " ") 134 | end_tab <- function() paste0(box_chars("l"), box_chars("h"), box_chars("h"), " ") 135 | -------------------------------------------------------------------------------- /man/pagedown_business_card_template.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_pagedown.R 3 | \name{pagedown_business_card_template} 4 | \alias{pagedown_business_card_template} 5 | \alias{pagedown_person} 6 | \title{Generate a full YAML template for your pagedown business card} 7 | \usage{ 8 | pagedown_business_card_template( 9 | name = yml_blank(), 10 | person = yml_blank(), 11 | title = yml_blank(), 12 | phone = yml_blank(), 13 | email = yml_blank(), 14 | url = yml_blank(), 15 | address = yml_blank(), 16 | logo = yml_blank(), 17 | .repeat = yml_blank(), 18 | paperwidth = yml_blank(), 19 | paperheight = yml_blank(), 20 | cardwidth = yml_blank(), 21 | cardheight = yml_blank(), 22 | cols = yml_blank(), 23 | rows = yml_blank(), 24 | mainfont = yml_blank(), 25 | googlefonts = yml_blank(), 26 | ... 27 | ) 28 | 29 | pagedown_person(...) 30 | } 31 | \arguments{ 32 | \item{name}{The name} 33 | 34 | \item{person}{When you are creating business cards for numerous people with 35 | shared information, passing values to the \code{person} field can override the 36 | default values, which can be any of the values accepted by this function. 37 | Use \code{pagedown_person()} to do so or manually provide them using \code{list(field = value)}.} 38 | 39 | \item{title}{The title of the person} 40 | 41 | \item{phone}{A phone number} 42 | 43 | \item{email}{An email address} 44 | 45 | \item{url}{A website URL} 46 | 47 | \item{address}{The address} 48 | 49 | \item{logo}{A path to a logo file} 50 | 51 | \item{.repeat}{The number of cards to repeat. Note that the actual YAML field 52 | is \code{repeat}.} 53 | 54 | \item{paperwidth}{The paper width} 55 | 56 | \item{paperheight}{The paper height} 57 | 58 | \item{cardwidth}{The width of the card} 59 | 60 | \item{cardheight}{The height of the card} 61 | 62 | \item{cols}{The number of columns in the card grid} 63 | 64 | \item{rows}{The rows of columns in the card grid} 65 | 66 | \item{mainfont}{The font} 67 | 68 | \item{googlefonts}{A character vector of Google Fonts} 69 | 70 | \item{...}{additional named R objects, such as characters or lists, to 71 | transform into YAML} 72 | } 73 | \value{ 74 | a \code{yml} object 75 | } 76 | \description{ 77 | pagedown has a unique output type to make business cards: 78 | \code{pagedown::business_card()}. \code{pagedown_business_card_template()} creates a 79 | YAML template to use for this output. What's unique about this output type is 80 | that almost all of the contents are supplied through YAML. An R Markdown file 81 | that only contains YAML related to the business card is enough to produce the 82 | output, although you can also customize the output in the body of the 83 | document (see the \href{https://pagedown.rbind.io/}{pagedown vignette}). A good 84 | workflow to write a business card is to use 85 | \code{pagedown_business_card_template()} to specify the YAML and pass it to 86 | \code{\link[=use_rmarkdown]{use_rmarkdown()}}, which you can then to knit into business cards. 87 | } 88 | \examples{ 89 | pagedown_business_card_template( 90 | name = "Jane Doe", 91 | title = "Miss Nobody", 92 | phone = "+1 123-456-7890", 93 | email = "jane.doe@example.com", 94 | url = "www.example.com", 95 | address = "2020 South Street, 96 | Sunshine, CA 90000", 97 | logo = "logo.png", 98 | .repeat = 12 99 | ) 100 | 101 | pagedown_business_card_template( 102 | phone = "+1 123-456-7890", 103 | url = "www.example.com", 104 | address = "2020 South Street, 105 | Sunshine, CA 90000", 106 | logo = "logo.png", 107 | person = list( 108 | pagedown_person( 109 | name = "Jane Doe", 110 | title = "Miss Nobody", 111 | email = "jane.doe@example.com", 112 | .repeat = 6 113 | ), 114 | pagedown_person( 115 | name = "John Doe", 116 | title = "Mister Nobody", 117 | phone = "+1 777-777-7777", # overrides the default phone 118 | email = "john.doe@example.com", 119 | .repeat = 6 120 | ) 121 | ), 122 | paperwidth = "8.5in", 123 | paperheight = "11in", 124 | cols = 4, 125 | rows = 3 126 | ) 127 | 128 | } 129 | \seealso{ 130 | \code{\link[=use_rmarkdown]{use_rmarkdown()}} 131 | 132 | Other pagedown: 133 | \code{\link{yml_pagedown_opts}()} 134 | } 135 | \concept{pagedown} 136 | -------------------------------------------------------------------------------- /man/use_file_yml.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/use_yml.R 3 | \name{use_yml_file} 4 | \alias{use_yml_file} 5 | \alias{use_output_yml} 6 | \alias{use_site_yml} 7 | \alias{use_navbar_yml} 8 | \alias{use_pkgdown_yml} 9 | \alias{use_bookdown_yml} 10 | \title{Write YAML to file} 11 | \usage{ 12 | use_yml_file( 13 | .yml = NULL, 14 | path, 15 | build_ignore = FALSE, 16 | git_ignore = FALSE, 17 | quiet = FALSE 18 | ) 19 | 20 | use_output_yml( 21 | .yml = NULL, 22 | path = ".", 23 | build_ignore = FALSE, 24 | git_ignore = FALSE, 25 | quiet = FALSE 26 | ) 27 | 28 | use_site_yml( 29 | .yml = NULL, 30 | path = ".", 31 | build_ignore = FALSE, 32 | git_ignore = FALSE, 33 | quiet = FALSE 34 | ) 35 | 36 | use_navbar_yml( 37 | .yml = NULL, 38 | path = ".", 39 | build_ignore = FALSE, 40 | git_ignore = FALSE, 41 | quiet = FALSE 42 | ) 43 | 44 | use_pkgdown_yml( 45 | .yml = NULL, 46 | path = ".", 47 | build_ignore = TRUE, 48 | git_ignore = FALSE, 49 | quiet = FALSE 50 | ) 51 | 52 | use_bookdown_yml( 53 | .yml = NULL, 54 | path = ".", 55 | build_ignore = FALSE, 56 | git_ignore = FALSE, 57 | quiet = FALSE 58 | ) 59 | } 60 | \arguments{ 61 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 62 | a \verb{yml_*()} function} 63 | 64 | \item{path}{a file path to write the file to} 65 | 66 | \item{build_ignore}{Logical. Should the file be added to the \code{.Rbuildignore} 67 | file?} 68 | 69 | \item{git_ignore}{Logical. Should the file be added to the \code{.gitignore} file?} 70 | 71 | \item{quiet}{Logical. Whether to message about what is happening.} 72 | } 73 | \description{ 74 | Write \code{yml} objects to a file. \code{use_yml_file()} writes to any given file 75 | name. \code{use_output_yml()} creates file \verb{_output.yml}, which can be used by 76 | multiple R Markdown documents. All documents located in the same directory as 77 | \verb{_output.yml} will inherit its output options. Options defined within 78 | document YAML headers will override those specified in \verb{_output.yml}. Note 79 | that \code{use_output_yml()} plucks the output field from \code{yml}; any other YAML 80 | top-level fields will be ignored. \code{use_site_yml} creates \verb{_site.yml} for use 81 | with R Markdown websites and third-party tools like the distill package (see 82 | \href{https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#}{the R Markdown book for more}). 83 | \code{use_navbar_yml} is a special type of site YAML that only specifies the 84 | navbar in \verb{_navbar.yml} \code{use_pkgdown_yml()} and \code{use_bookdown_yml()} write 85 | YAML files specific to those packages; see the 86 | \href{https://pkgdown.r-lib.org/articles/pkgdown.html}{pkgdown} and 87 | \href{https://bookdown.org/yihui/bookdown/configuration.html}{blogdown} 88 | documentation for more. 89 | } 90 | \details{ 91 | By default, the yaml package adds a new line to the end of files. Some 92 | environments, such as RStudio Projects, allow you to append new lines 93 | automatically. Thus, you may end up with 2 new lines at the end of your file. 94 | If you'd like to automatically remove the last new line in the file, set 95 | \code{options(ymlthis.remove_blank_line = TRUE)}. 96 | } 97 | \seealso{ 98 | yml_bookdown_opts yml_bookdown_site yml_pkgdown yml_pkgdown_articles 99 | yml_pkgdown_docsearch yml_pkgdown_figures yml_pkgdown_news 100 | yml_pkgdown_reference 101 | 102 | Other yml: 103 | \code{\link{asis_yaml_output}()}, 104 | \code{\link{bib2yml}()}, 105 | \code{\link{draw_yml_tree}()}, 106 | \code{\link{has_field}()}, 107 | \code{\link{read_json}()}, 108 | \code{\link{use_yml_defaults}()}, 109 | \code{\link{use_yml}()}, 110 | \code{\link{yml_author}()}, 111 | \code{\link{yml_blogdown_opts}()}, 112 | \code{\link{yml_bookdown_opts}()}, 113 | \code{\link{yml_citations}()}, 114 | \code{\link{yml_clean}()}, 115 | \code{\link{yml_distill_opts}()}, 116 | \code{\link{yml_latex_opts}()}, 117 | \code{\link{yml_output}()}, 118 | \code{\link{yml_pagedown_opts}()}, 119 | \code{\link{yml_params}()}, 120 | \code{\link{yml_pkgdown}()}, 121 | \code{\link{yml_reference}()}, 122 | \code{\link{yml_replace}()}, 123 | \code{\link{yml_resource_files}()}, 124 | \code{\link{yml_rsconnect_email}()}, 125 | \code{\link{yml_rticles_opts}()}, 126 | \code{\link{yml_runtime}()}, 127 | \code{\link{yml_site_opts}()}, 128 | \code{\link{yml_toc}()}, 129 | \code{\link{yml_vignette}()} 130 | } 131 | \concept{yml} 132 | -------------------------------------------------------------------------------- /R/yml_rsconnect.R: -------------------------------------------------------------------------------- 1 | #' Set YAML for Scheduled Emails in RStudio Connect 2 | #' 3 | #' RStudio Connect allows you to schedule emails to send using R Markdown. It 4 | #' uses a special type of YAML using the top-level field `rmd_output_metadata` 5 | #' that tells RStudio Connect about the email output. Several `rsc_*` fields 6 | #' exist to specify different components of the email, which can be set in the 7 | #' YAML header or programmatically using `rmarkdown::output_metadata()`. See the 8 | #' [RStudio Connect 9 | #' documentation](https://docs.rstudio.com/connect/1.7.2/user/r-markdown.html) 10 | #' for more. `yml_output_metadata()` allows you to add any type of content to 11 | #' the `rmd_output_metadata` field. 12 | #' 13 | #' @template describe_yml_param 14 | #' @param rsc_email_subject The subject of the email. A report without an 15 | #' `rsc_email_subject` entry uses its published document name. 16 | #' @param rsc_email_body_html,rsc_email_body_text The body of the email, either 17 | #' in plain text or HTML. A report with neither entry uses an automatically 18 | #' generated, plain-text body with a link to the report’s URL. 19 | #' @param rsc_email_images Images to embed in the email. The embedded image must 20 | #' have a Content ID that is used in the body of the HTML and when providing 21 | #' the image to `rsc_email_images`, and the image itself must be 22 | #' base64-encoded, e.g. with the base64enc package. 23 | #' @param rsc_output_files A vector of file names that should be available after 24 | #' the report has rendered. If you list a file that does not exist after 25 | #' rendering your report, Connect will log a message but continue trying to 26 | #' processing the other files listed. If the output files are not generated 27 | #' during the rendering of your report, then you will also need to list them 28 | #' in `resource_files` when you upload your report to Connect. 29 | #' @param rsc_email_attachments A vector of file names that should be attached 30 | #' to the email. 31 | #' @param rsc_email_suppress_scheduled Logical. Should the email schedule be 32 | #' suppressed? Default is `FALSE`. 33 | #' @param rsc_email_suppress_report_attachment Logical. Should the rendered 34 | #' document be included as an attachment? Default is `TRUE`. 35 | #' @param resource_files A file or files to host on RStudio Connect that is 36 | #' *not* generated by your report, e.g. an existing file. 37 | #' @template describe_dots_param 38 | #' 39 | #' @template describe_yml_output 40 | #' @export 41 | #' 42 | #' @examples 43 | #' 44 | #' yml() %>% 45 | #' yml_rsconnect_email( 46 | #' rsc_email_subject = "Quarterly report", 47 | #' rsc_output_files = "data.csv", 48 | #' rsc_email_attachments = c("attachment_1.csv", "attachment_2.csv") 49 | #' ) 50 | yml_rsconnect_email <- function( 51 | .yml, 52 | rsc_email_subject = yml_blank(), 53 | rsc_email_body_html = yml_blank(), 54 | rsc_email_body_text = yml_blank(), 55 | rsc_email_images = yml_blank(), 56 | rsc_output_files = yml_blank(), 57 | rsc_email_attachments = yml_blank(), 58 | rsc_email_suppress_scheduled = yml_blank(), 59 | rsc_email_suppress_report_attachment = yml_blank(), 60 | resource_files = yml_blank(), 61 | ... 62 | ) { 63 | rsconnect_email_opts <- list( 64 | rmd_output_metadata = list( 65 | rsc_email_subject = rsc_email_subject, 66 | rsc_email_body_html = rsc_email_body_html, 67 | rsc_email_body_text = rsc_email_body_text, 68 | rsc_email_images = rsc_email_images, 69 | rsc_output_files = rsc_output_files, 70 | rsc_email_attachments = rsc_email_attachments, 71 | rsc_email_suppress_scheduled = rsc_email_suppress_scheduled, 72 | rsc_email_suppress_report_attachment = rsc_email_suppress_report_attachment, 73 | ... 74 | ) %>% purrr::discard(is_yml_blank), 75 | resource_files = resource_files 76 | ) %>% purrr::discard(is_yml_blank) 77 | 78 | warn_if_duplicate_fields(.yml, rsconnect_email_opts) 79 | .yml[names(rsconnect_email_opts)] <- rsconnect_email_opts 80 | 81 | .yml 82 | } 83 | 84 | #' @export 85 | #' @rdname yml_rsconnect_email 86 | yml_output_metadata <- function( 87 | .yml, 88 | ... 89 | ) { 90 | rmd_output_metadata_list <- list( 91 | rmd_output_metadata = list( 92 | ... 93 | ) %>% purrr::discard(is_yml_blank) 94 | ) 95 | 96 | warn_if_duplicate_fields(.yml, rmd_output_metadata_list) 97 | .yml[names(rmd_output_metadata_list)] <- rmd_output_metadata_list 98 | 99 | .yml 100 | } 101 | -------------------------------------------------------------------------------- /man/use_yml.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/use_yml.R 3 | \name{use_yml} 4 | \alias{use_yml} 5 | \alias{use_rmarkdown} 6 | \alias{use_index_rmd} 7 | \title{Copy YAML code to your clipboard or write to a new R Markdown file} 8 | \usage{ 9 | use_yml(.yml = last_yml()) 10 | 11 | use_rmarkdown( 12 | .yml = last_yml(), 13 | path, 14 | template = NULL, 15 | include_yaml = TRUE, 16 | include_body = TRUE, 17 | body = NULL, 18 | quiet = FALSE, 19 | open_doc = interactive(), 20 | overwrite = getOption("usethis.overwrite", FALSE) 21 | ) 22 | 23 | use_index_rmd( 24 | .yml = last_yml(), 25 | path, 26 | template = NULL, 27 | include_yaml = TRUE, 28 | include_body = TRUE, 29 | body = NULL, 30 | quiet = FALSE, 31 | open_doc = interactive() 32 | ) 33 | } 34 | \arguments{ 35 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 36 | a \verb{yml_*()} function} 37 | 38 | \item{path}{A file path to write R Markdown file to} 39 | 40 | \item{template}{An existing R Markdown file to read YAML from} 41 | 42 | \item{include_yaml}{Logical. Include the template YAML?} 43 | 44 | \item{include_body}{Logical. Include the template body?} 45 | 46 | \item{body}{A character vector to use in the body of the R Markdown file. If 47 | no template is set, checks \code{getOption("ymlthis.rmd_body")} (see 48 | \code{\link[=use_rmd_defaults]{use_rmd_defaults()}}) and otherwise uses \code{\link[=setup_chunk]{setup_chunk()}}.} 49 | 50 | \item{quiet}{Logical. Whether to message about what is happening.} 51 | 52 | \item{open_doc}{Logical. Open the document after it's created? By default, 53 | this is \code{TRUE} if it is an interactive session and \code{FALSE} if not. Also 54 | checks that RStudio is available.} 55 | 56 | \item{overwrite}{Logical. If \code{TRUE}, overwrites the file without asking for 57 | permission. If \code{FALSE}, asks interactively if the user wishes to do so. 58 | Checks the user's \code{usethis.overwrite} option if set and is otherwise 59 | \code{FALSE} by default.} 60 | } 61 | \value{ 62 | \code{use_yml()} invisibly returns the input \code{yml} object 63 | } 64 | \description{ 65 | \code{use_yml()} takes a \code{yml} object and puts the resulting YAML on your 66 | clipboard to paste into an R Markdown or YAML file. \code{use_rmarkdown()} takes 67 | the \code{yml} object and writes it to a new R Markdown file. You can add text to 68 | include in the body of the file. If it's not specified, \code{use_rmarkdown()} 69 | will use \code{\link[=setup_chunk]{setup_chunk()}} by default. You can also set a default for \code{body} 70 | using \code{options(ymlthis.rmd_body = "{your text}")}; see \code{\link[=use_rmd_defaults]{use_rmd_defaults()}}. 71 | Together with specifying default YAML (see \code{\link[=use_yml_defaults]{use_yml_defaults()}}), 72 | \code{use_rmarkdown()} also serves as an ad-hoc way to make R Markdown templates. 73 | You may also supply \code{use_rmarkdown()} with an existing R Markdown file from 74 | which to read the YAML header; the YAML header from the template is then 75 | combined with \code{.yml}, if it's supplied, and written to a new file. 76 | \code{use_index_rmd()} is a wrapper around \code{use_rmarkdown()} that specifically 77 | writes to a file called \code{index.Rmd}. By default, \code{use_yml()} and 78 | \code{use_rmarkdown()} use the most recently printed YAML via \code{\link[=last_yml]{last_yml()}}. 79 | } 80 | \seealso{ 81 | \code{\link[=code_chunk]{code_chunk()}} \code{\link[=setup_chunk]{setup_chunk()}} 82 | 83 | Other yml: 84 | \code{\link{asis_yaml_output}()}, 85 | \code{\link{bib2yml}()}, 86 | \code{\link{draw_yml_tree}()}, 87 | \code{\link{has_field}()}, 88 | \code{\link{read_json}()}, 89 | \code{\link{use_yml_defaults}()}, 90 | \code{\link{use_yml_file}()}, 91 | \code{\link{yml_author}()}, 92 | \code{\link{yml_blogdown_opts}()}, 93 | \code{\link{yml_bookdown_opts}()}, 94 | \code{\link{yml_citations}()}, 95 | \code{\link{yml_clean}()}, 96 | \code{\link{yml_distill_opts}()}, 97 | \code{\link{yml_latex_opts}()}, 98 | \code{\link{yml_output}()}, 99 | \code{\link{yml_pagedown_opts}()}, 100 | \code{\link{yml_params}()}, 101 | \code{\link{yml_pkgdown}()}, 102 | \code{\link{yml_reference}()}, 103 | \code{\link{yml_replace}()}, 104 | \code{\link{yml_resource_files}()}, 105 | \code{\link{yml_rsconnect_email}()}, 106 | \code{\link{yml_rticles_opts}()}, 107 | \code{\link{yml_runtime}()}, 108 | \code{\link{yml_site_opts}()}, 109 | \code{\link{yml_toc}()}, 110 | \code{\link{yml_vignette}()} 111 | } 112 | \concept{yml} 113 | -------------------------------------------------------------------------------- /man/yml_rsconnect_email.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_rsconnect.R 3 | \name{yml_rsconnect_email} 4 | \alias{yml_rsconnect_email} 5 | \alias{yml_output_metadata} 6 | \title{Set YAML for Scheduled Emails in RStudio Connect} 7 | \usage{ 8 | yml_rsconnect_email( 9 | .yml, 10 | rsc_email_subject = yml_blank(), 11 | rsc_email_body_html = yml_blank(), 12 | rsc_email_body_text = yml_blank(), 13 | rsc_email_images = yml_blank(), 14 | rsc_output_files = yml_blank(), 15 | rsc_email_attachments = yml_blank(), 16 | rsc_email_suppress_scheduled = yml_blank(), 17 | rsc_email_suppress_report_attachment = yml_blank(), 18 | resource_files = yml_blank(), 19 | ... 20 | ) 21 | 22 | yml_output_metadata(.yml, ...) 23 | } 24 | \arguments{ 25 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 26 | a \verb{yml_*()} function} 27 | 28 | \item{rsc_email_subject}{The subject of the email. A report without an 29 | \code{rsc_email_subject} entry uses its published document name.} 30 | 31 | \item{rsc_email_body_html, rsc_email_body_text}{The body of the email, either 32 | in plain text or HTML. A report with neither entry uses an automatically 33 | generated, plain-text body with a link to the report’s URL.} 34 | 35 | \item{rsc_email_images}{Images to embed in the email. The embedded image must 36 | have a Content ID that is used in the body of the HTML and when providing 37 | the image to \code{rsc_email_images}, and the image itself must be 38 | base64-encoded, e.g. with the base64enc package.} 39 | 40 | \item{rsc_output_files}{A vector of file names that should be available after 41 | the report has rendered. If you list a file that does not exist after 42 | rendering your report, Connect will log a message but continue trying to 43 | processing the other files listed. If the output files are not generated 44 | during the rendering of your report, then you will also need to list them 45 | in \code{resource_files} when you upload your report to Connect.} 46 | 47 | \item{rsc_email_attachments}{A vector of file names that should be attached 48 | to the email.} 49 | 50 | \item{rsc_email_suppress_scheduled}{Logical. Should the email schedule be 51 | suppressed? Default is \code{FALSE}.} 52 | 53 | \item{rsc_email_suppress_report_attachment}{Logical. Should the rendered 54 | document be included as an attachment? Default is \code{TRUE}.} 55 | 56 | \item{resource_files}{A file or files to host on RStudio Connect that is 57 | \emph{not} generated by your report, e.g. an existing file.} 58 | 59 | \item{...}{additional named R objects, such as characters or lists, to 60 | transform into YAML} 61 | } 62 | \value{ 63 | a \code{yml} object 64 | } 65 | \description{ 66 | RStudio Connect allows you to schedule emails to send using R Markdown. It 67 | uses a special type of YAML using the top-level field \code{rmd_output_metadata} 68 | that tells RStudio Connect about the email output. Several \verb{rsc_*} fields 69 | exist to specify different components of the email, which can be set in the 70 | YAML header or programmatically using \code{rmarkdown::output_metadata()}. See the 71 | \href{https://docs.rstudio.com/connect/1.7.2/user/r-markdown.html}{RStudio Connect documentation} 72 | for more. \code{yml_output_metadata()} allows you to add any type of content to 73 | the \code{rmd_output_metadata} field. 74 | } 75 | \examples{ 76 | 77 | yml() \%>\% 78 | yml_rsconnect_email( 79 | rsc_email_subject = "Quarterly report", 80 | rsc_output_files = "data.csv", 81 | rsc_email_attachments = c("attachment_1.csv", "attachment_2.csv") 82 | ) 83 | } 84 | \seealso{ 85 | Other yml: 86 | \code{\link{asis_yaml_output}()}, 87 | \code{\link{bib2yml}()}, 88 | \code{\link{draw_yml_tree}()}, 89 | \code{\link{has_field}()}, 90 | \code{\link{read_json}()}, 91 | \code{\link{use_yml_defaults}()}, 92 | \code{\link{use_yml_file}()}, 93 | \code{\link{use_yml}()}, 94 | \code{\link{yml_author}()}, 95 | \code{\link{yml_blogdown_opts}()}, 96 | \code{\link{yml_bookdown_opts}()}, 97 | \code{\link{yml_citations}()}, 98 | \code{\link{yml_clean}()}, 99 | \code{\link{yml_distill_opts}()}, 100 | \code{\link{yml_latex_opts}()}, 101 | \code{\link{yml_output}()}, 102 | \code{\link{yml_pagedown_opts}()}, 103 | \code{\link{yml_params}()}, 104 | \code{\link{yml_pkgdown}()}, 105 | \code{\link{yml_reference}()}, 106 | \code{\link{yml_replace}()}, 107 | \code{\link{yml_resource_files}()}, 108 | \code{\link{yml_rticles_opts}()}, 109 | \code{\link{yml_runtime}()}, 110 | \code{\link{yml_site_opts}()}, 111 | \code{\link{yml_toc}()}, 112 | \code{\link{yml_vignette}()} 113 | } 114 | \concept{yml} 115 | -------------------------------------------------------------------------------- /man/yml_reference.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_citations.R 3 | \name{yml_reference} 4 | \alias{yml_reference} 5 | \alias{reference} 6 | \title{Write references as YAML fields} 7 | \usage{ 8 | yml_reference(.yml, ..., .bibentry = NULL) 9 | 10 | reference(id = NULL, ...) 11 | } 12 | \arguments{ 13 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 14 | a \verb{yml_*()} function} 15 | 16 | \item{...}{Fields relevant to the citation (e.g. bibtex fields)} 17 | 18 | \item{.bibentry}{An object created by \code{bibentry()} or \code{citation()}. Note that 19 | this requires pandoc-citeproc to be installed.} 20 | 21 | \item{id}{a character vector to use as the reference ID} 22 | } 23 | \value{ 24 | a \code{yml} object 25 | } 26 | \description{ 27 | \code{yml_reference()} creates YAML fields for references to be used in citation. 28 | \code{reference()} is a simple function to add references to \code{yml_reference()}. The 29 | easiest way to add references to an R Markdown file is to use a bibliography 30 | file, such as .bib, in the \code{bibliography} field (see \code{\link[=yml_citations]{yml_citations()}}). For 31 | documents with very few references, however, it might be useful to make the 32 | references self-contained in the YAML. \code{yml_reference()} can also transform to 33 | YAML \code{bibentry} and \code{citation} objects created by\code{\link[=bibentry]{bibentry()}} and 34 | \code{\link[=citation]{citation()}}. To cite many R packages and convert the references to YAML, 35 | it may be better to use \code{\link[knitr:write_bib]{knitr::write_bib()}} to write a bibliography file and 36 | convert it with \code{\link[=bib2yml]{bib2yml()}}. 37 | } 38 | \examples{ 39 | 40 | ref <- reference( 41 | id = "fenner2012a", 42 | title = "One-click science marketing", 43 | author = list( 44 | family = "Fenner", 45 | given = "Martin" 46 | ), 47 | `container-title` = "Nature Materials", 48 | volume = 11L, 49 | URL = "https://doi.org/10.1038/nmat3283", 50 | DOI = "10.1038/nmat3283", 51 | issue = 4L, 52 | publisher = "Nature Publishing Group", 53 | page = "261-263", 54 | type = "article-journal", 55 | issued = list( 56 | year = 2012, 57 | month = 3 58 | ) 59 | ) 60 | 61 | yml() \%>\% 62 | yml_reference(ref) 63 | 64 | # from ?bibentry 65 | bref <- c( 66 | bibentry( 67 | bibtype = "Manual", 68 | title = "boot: Bootstrap R (S-PLUS) Functions", 69 | author = c( 70 | person("Angelo", "Canty", role = "aut", 71 | comment = "S original"), 72 | person(c("Brian", "D."), "Ripley", role = c("aut", "trl", "cre"), 73 | comment = "R port, author of parallel support", 74 | email = "ripley@stats.ox.ac.uk") 75 | ), 76 | year = "2012", 77 | note = "R package version 1.3-4", 78 | url = "https://CRAN.R-project.org/package=boot", 79 | key = "boot-package" 80 | ), 81 | 82 | bibentry( 83 | bibtype = "Book", 84 | title = "Bootstrap Methods and Their Applications", 85 | author = as.person("Anthony C. Davison [aut], David V. Hinkley [aut]"), 86 | year = "1997", 87 | publisher = "Cambridge University Press", 88 | address = "Cambridge", 89 | isbn = "0-521-57391-2", 90 | url = "http://statwww.epfl.ch/davison/BMA/", 91 | key = "boot-book" 92 | ) 93 | ) 94 | \donttest{ 95 | # requires pandoc-citeproc to be installed 96 | yml() \%>\% 97 | yml_reference(.bibentry = bref) 98 | 99 | yml() \%>\% 100 | yml_reference(.bibentry = citation("purrr")) 101 | } 102 | } 103 | \seealso{ 104 | Other yml: 105 | \code{\link{asis_yaml_output}()}, 106 | \code{\link{bib2yml}()}, 107 | \code{\link{draw_yml_tree}()}, 108 | \code{\link{has_field}()}, 109 | \code{\link{read_json}()}, 110 | \code{\link{use_yml_defaults}()}, 111 | \code{\link{use_yml_file}()}, 112 | \code{\link{use_yml}()}, 113 | \code{\link{yml_author}()}, 114 | \code{\link{yml_blogdown_opts}()}, 115 | \code{\link{yml_bookdown_opts}()}, 116 | \code{\link{yml_citations}()}, 117 | \code{\link{yml_clean}()}, 118 | \code{\link{yml_distill_opts}()}, 119 | \code{\link{yml_latex_opts}()}, 120 | \code{\link{yml_output}()}, 121 | \code{\link{yml_pagedown_opts}()}, 122 | \code{\link{yml_params}()}, 123 | \code{\link{yml_pkgdown}()}, 124 | \code{\link{yml_replace}()}, 125 | \code{\link{yml_resource_files}()}, 126 | \code{\link{yml_rsconnect_email}()}, 127 | \code{\link{yml_rticles_opts}()}, 128 | \code{\link{yml_runtime}()}, 129 | \code{\link{yml_site_opts}()}, 130 | \code{\link{yml_toc}()}, 131 | \code{\link{yml_vignette}()} 132 | 133 | Other citations: 134 | \code{\link{bib2yml}()}, 135 | \code{\link{yml_citations}()} 136 | } 137 | \concept{citations} 138 | \concept{yml} 139 | -------------------------------------------------------------------------------- /R/yml_helpers.R: -------------------------------------------------------------------------------- 1 | #' Return a blank object to be discarded from YAML 2 | #' 3 | #' ymlthis treats `NULL`, `NA`, and other common argument defaults as literal 4 | #' (e.g. `author = NULL` will produce "author: null"). `yml_blank()` is a helper 5 | #' function to indicate that the field should not be included. `yml_blank()` is 6 | #' primarily used as a default argument for fields that should not be included 7 | #' by default. 8 | #' 9 | #' @param x a field from a `yml` object 10 | #' @return a `yml_blank` object 11 | #' @export 12 | #' 13 | #' @examples 14 | #' 15 | #' yml() %>% 16 | #' yml_replace(author = yml_blank()) %>% 17 | #' yml_discard(~is_yml_blank(.x)) 18 | #' 19 | #' 20 | #' @rdname yml_blank 21 | #' @seealso [yml_discard()], [yml_replace()] 22 | yml_blank <- function() { 23 | structure(list(), class = "yml_blank") 24 | } 25 | 26 | null_if_blank <- function(.x) { 27 | if (is_yml_blank(.x)) { 28 | return(NULL) 29 | } 30 | 31 | .x 32 | } 33 | 34 | 35 | #' @export 36 | #' @rdname yml_blank 37 | is_yml_blank <- function(x) { 38 | inherits(x, "yml_blank") 39 | } 40 | 41 | #' Write YAML field or content verbatim 42 | #' 43 | #' `yml_verbatim()` is a helper function to write YAML precisely as given to the 44 | #' `yml_*()` function rather than the defaults in ymlthis and yaml. ymlthis uses 45 | #' the yaml package to check for valid syntax; yaml and ymlthis together make 46 | #' decisions about how to write syntax, which can often be done in numerous 47 | #' valid ways. See [yaml::as.yaml()] for more details. 48 | #' 49 | #' @param x a character vector 50 | #' 51 | #' @return an object of class `verbatim` 52 | #' @export 53 | #' 54 | #' @examples 55 | #' # "yes" and "no" serve as alternatives to `true` and `false`. This writes 56 | #' # "yes" literally. 57 | #' yml_verbatim("yes") 58 | yml_verbatim <- function(x) { 59 | structure(x, class = "verbatim") 60 | } 61 | 62 | #' Take code and write it as valid YAML 63 | #' 64 | #' `yml_code()` takes R code and writes it as valid YAML to be evaluated during 65 | #' knitting. Note that `yml_code()` does not evaluate or validate the R code but 66 | #' only captures it to use in the YAML field. R code needs to be formatted 67 | #' differently when using in the `params` field for parameterized reports; 68 | #' `yml_params_code` will format this correctly for you. 69 | #' 70 | #' @param x valid R code 71 | #' 72 | #' @return a character vector with class `verbatim` 73 | #' @export 74 | #' 75 | #' @examples 76 | #' 77 | #' yml_empty() %>% 78 | #' yml_date(yml_code(sys.Date())) 79 | #' 80 | #' yml_empty() %>% 81 | #' yml_params(date = yml_params_code(sys.Date())) 82 | #' 83 | #' @seealso [yml_verbatim()] 84 | yml_code <- function(x) { 85 | x <- rlang::enquo(x) 86 | glue::glue("`r {rlang::quo_text(x)} `") %>% 87 | yml_verbatim() 88 | } 89 | 90 | #' @export 91 | #' @rdname yml_code 92 | yml_params_code <- function(x) { 93 | x <- rlang::enquo(x) 94 | x <- rlang::quo_text(x) 95 | attr(x, "tag") <- "!r" 96 | 97 | x 98 | } 99 | 100 | 101 | #' Include content within output 102 | #' 103 | #' `includes2()` is a version of the `includes()` helper function from rmarkdown 104 | #' that uses `yml_blank()` instead of `NULL` as the argument defaults, as 105 | #' ymlthis treats NULLs as literal YAML syntax ("null"). 106 | #' 107 | #' @param in_header One or more files with content to be included in the header 108 | #' of the document. 109 | #' @param before_body One or more files with content to be included before the 110 | #' document body. 111 | #' @param after_body One or more files with content to be included after the 112 | #' document body. 113 | #' 114 | #' @return a list 115 | #' @export 116 | #' 117 | #' @examples 118 | #'\donttest{ 119 | #' yml() %>% 120 | #' yml_output( 121 | #' pdf_document(includes = includes2(after_body = "footer.tex")) 122 | #' ) 123 | #'} 124 | includes2 <- function(in_header = yml_blank(), before_body = yml_blank(), after_body = yml_blank()) { 125 | includes_list <- list( 126 | in_header = in_header, 127 | before_body = before_body, 128 | after_body = after_body 129 | ) 130 | 131 | purrr::discard(includes_list, is_yml_blank) 132 | } 133 | 134 | #' Check if field exists in YAML 135 | #' 136 | #' `has_field()` retrieves the names of all fields (including nested fields) and 137 | #' checks if `field` is among them. 138 | #' 139 | #' @template describe_yml_param 140 | #' @param field A character vector, the name of the field(s) to check for 141 | #' 142 | #' @return logical 143 | #' @export 144 | #' 145 | #' @examples 146 | #' 147 | #' has_field(yml(), "author") 148 | #' has_field(yml(), "toc") 149 | #' 150 | has_field <- function(.yml, field) { 151 | fields <- flatten_yml_names(.yml) 152 | field %in% fields 153 | } 154 | -------------------------------------------------------------------------------- /R/convert_metadata.R: -------------------------------------------------------------------------------- 1 | #' Read and write to JSON and TOML 2 | #' 3 | #' Read JSON and TOML files in as `yml` objects with `read_*()`. Write `yml` 4 | #' objects out as JSON and YAML files with `write_as_*()`. You can also provide 5 | #' `write_as_*()` a path to an existing `.yml` file to translate to JSON or 6 | #' TOML. These functions rely on Hugo and blogdown, so you must have blogdown 7 | #' installed. 8 | #' 9 | #' @template describe_yml_param 10 | #' @param path a path to a JSON or TOML file 11 | #' @param out The path to write out to. If `NULL`, will write to the `path` but 12 | #' change the file extension to `.toml` or `.json`. 13 | #' @param quiet Logical. Whether to message about what is happening. 14 | #' @inheritParams use_yml_file 15 | #' 16 | #' @return a `yml` object (if reading) or the path (if writing) 17 | #' @export 18 | read_json <- function(path) { 19 | convert_metadata(path = path, to = "YAML") 20 | } 21 | 22 | #' @export 23 | #' @rdname read_json 24 | read_toml <- function(path) { 25 | convert_metadata(path = path, to = "YAML") 26 | } 27 | 28 | #' @export 29 | #' @rdname read_json 30 | write_as_json <- function(.yml = NULL, path = NULL, out = NULL, build_ignore = FALSE, git_ignore = FALSE, quiet = FALSE) { 31 | write_as_metadata( 32 | .yml = .yml, 33 | path = path, 34 | out = out, 35 | extension = ".json", 36 | to = "JSON", 37 | build_ignore = build_ignore, 38 | git_ignore = git_ignore, 39 | quiet = quiet 40 | ) 41 | } 42 | 43 | #' @export 44 | #' @rdname read_json 45 | write_as_toml <- function(.yml = NULL, path = NULL, out = NULL, build_ignore = FALSE, git_ignore = FALSE, quiet = FALSE) { 46 | write_as_metadata( 47 | .yml = .yml, 48 | path = path, 49 | out = out, 50 | extension = ".toml", 51 | to = "TOML", 52 | build_ignore = build_ignore, 53 | git_ignore = git_ignore, 54 | quiet = quiet 55 | ) 56 | } 57 | 58 | write_as_metadata <- function(.yml, path, out, extension, to, build_ignore, git_ignore, quiet = FALSE) { 59 | stop_if_both_args_given(.yml, path) 60 | 61 | if (!is.null(.yml)) { 62 | path <- write_temp_yaml(.yml) 63 | on.exit(unlink(path), add = TRUE) 64 | } 65 | if (is.null(out)) out <- swap_extension(path, extension) 66 | if (build_ignore) usethis::use_build_ignore(out) 67 | if (git_ignore) usethis::use_git_ignore(out) 68 | 69 | convert_metadata(path = path, to = to, out = out, quiet = FALSE) 70 | } 71 | 72 | swap_extension <- function(path, ext) paste0(fs::path_ext_remove(path), ext) 73 | 74 | stop_if_both_args_given <- function(.yml, path) { 75 | if (!is.null(.yml) && !is.null(path)) { 76 | stop( 77 | "You cannot specify both a `yml` object and a file to convert", 78 | call. = FALSE 79 | ) 80 | } 81 | } 82 | 83 | write_temp_yaml <- function(.yml) { 84 | .file <- tempfile(fileext = ".yml") 85 | yml_txt <- yaml::as.yaml( 86 | .yml, 87 | handlers = yml_handlers(), 88 | column.major = FALSE 89 | ) 90 | writeLines(yml_txt, .file) 91 | 92 | .file 93 | } 94 | 95 | convert_metadata <- function(path, to = c("YAML", "TOML", "JSON"), out = NULL, quiet = FALSE) { 96 | stop_if_blogdown_not_installed() 97 | on.exit(unlink_temporary_dir(), add = TRUE) 98 | to <- match.arg(to) 99 | 100 | file_to_convert <- fs::path_file(path) %>% 101 | fs::path_ext_remove() %>% 102 | paste0(".md") 103 | file_to_convert <- file.path(temporary_dir(), "content", file_to_convert) 104 | file_type <- fs::path_ext(path) %>% 105 | tolower() 106 | 107 | fs::dir_create(file.path(temporary_dir(), "content")) 108 | rewrite_with_fences(path, file_to_convert, file_type = file_type) 109 | 110 | writeLines( 111 | c("baseurl = \"/\"", "builddrafts = true"), 112 | file.path(temporary_dir(), "config.toml") 113 | ) 114 | 115 | withr::with_dir( 116 | temporary_dir(), 117 | blogdown::hugo_cmd( 118 | args = c("convert", paste0("to", to), "--unsafe"), 119 | stdout = TRUE 120 | ) 121 | ) 122 | 123 | if (to == "YAML") { 124 | post_yml <- yaml::yaml.load_file(file_to_convert) %>% 125 | as_yml() 126 | 127 | return(post_yml) 128 | } 129 | 130 | file_txt <- readLines(file_to_convert) %>% 131 | purrr::discard(~.x %in% c("---", "+++", "...")) 132 | 133 | usethis::write_over(out, file_txt, quiet = quiet) 134 | invisible(out) 135 | } 136 | 137 | rewrite_with_fences <- function(from, to, file_type) { 138 | fences <- switch( 139 | file_type, 140 | yml = "---", 141 | yaml = "---", 142 | toml = "+++", 143 | json = NULL 144 | ) 145 | 146 | file_txt <- readLines(from) 147 | if (!is.null(fences) && file_txt[[1]] != fences) { 148 | file_txt <- c(fences, file_txt, fences) 149 | } 150 | 151 | writeLines(file_txt, to) 152 | } 153 | -------------------------------------------------------------------------------- /R/yml_rticles.R: -------------------------------------------------------------------------------- 1 | #' Set YAML related to rticles output formats 2 | #' 3 | #' The rticles package include numerous output formats specific to academic 4 | #' journals. All of these can take YAML similar to `pdf_document()`. 5 | #' Additionally, two templates include custom YAML, `rticles::sage_article()` 6 | #' and `rticles::sim_article()`. See the help pages for these functions for more 7 | #' details and the sources of the LaTeX templates used for each. 8 | #' 9 | #' @template describe_yml_param 10 | #' @param title Title of the manuscript 11 | #' @param runninghead A character vector, a short author list for the header 12 | #' (sage_article) 13 | #' @param author A list of authors, containing `name` and `num` fields 14 | #' (sage_article, sim_article). Use `rticles_author()` or a list to specify. 15 | #' @param authormark A character vector, the short author list for the header 16 | #' (sim_article) 17 | #' @param address list containing `num` and `org` for defining author 18 | #' affiliations (sage_article, sim_article). Use `rticles_address()` or a list 19 | #' to specify. 20 | #' @param corrauth corresponding author `name` and `address` (sage_article). Use 21 | #' `rticles_corr_author()` or a list to specify. 22 | #' @param corres `author` and `address` for correspondence (sim_article). Use 23 | #' `rticles_corr_author()` or a list to specify. 24 | #' @param email The email of the correspondence author (sage_article) 25 | #' @param abstract The abstract, limited to 200 words (sage_article), 250 words 26 | #' (sim_article) 27 | #' @param received,revised,accepted The dates of submission, revision, and 28 | #' acceptance of the manuscript (sim_article) 29 | #' @param keywords The keywords for the article (sage_article), up to 6 keywords 30 | #' (sim_article) 31 | #' @param bibliography BibTeX `.bib` file name (sage_article, sim_article) 32 | #' @param longtable Logical. Include the longtable package? Used by default from 33 | #' pandoc to convert markdown to LaTeX code (sim_article) 34 | #' @param classoption a character vector of `classoption` options for the 35 | #' `sagej` class (sage_article) 36 | #' @param header_includes additional LaTeX code to include in the header, before 37 | #' the `\\begin\{document\}` statement (sage_article, sim_article). Note that 38 | #' the actual YAML field is `header-includes` 39 | #' @param include_after additional LaTeX code to include before the 40 | #' `\\end\{document\}` statement (sage_article, sim_article). Note that the 41 | #' actual YAML field is `include-after`. 42 | #' @template describe_dots_param 43 | #' 44 | #' @template describe_yml_output 45 | #' @export 46 | #' 47 | #' @examples 48 | #' 49 | #' yml() %>% 50 | #' yml_rticles_opts(received = "09-12-2014") 51 | #' 52 | yml_rticles_opts <- function( 53 | .yml, 54 | title = yml_blank(), 55 | runninghead = yml_blank(), 56 | author = yml_blank(), 57 | authormark = yml_blank(), 58 | address = yml_blank(), 59 | corrauth = yml_blank(), 60 | corres = yml_blank(), 61 | email = yml_blank(), 62 | abstract = yml_blank(), 63 | received = yml_blank(), 64 | revised = yml_blank(), 65 | accepted = yml_blank(), 66 | keywords = yml_blank(), 67 | bibliography = yml_blank(), 68 | longtable = yml_blank(), 69 | classoption = yml_blank(), 70 | header_includes = yml_blank(), 71 | include_after = yml_blank(), 72 | ... 73 | ) { 74 | rticles_opts <- list( 75 | title = title, 76 | runninghead = runninghead, 77 | author = author, 78 | address = address, 79 | authormark = authormark, 80 | corrauth = corrauth, 81 | corres = corres, 82 | email = email, 83 | abstract = abstract, 84 | received = received, 85 | revised = revised, 86 | accepted = accepted, 87 | keywords = keywords, 88 | bibliography = bibliography, 89 | longtable = longtable, 90 | classoption = classoption, 91 | "header-includes" = header_includes, 92 | "include-after" = include_after, 93 | ... 94 | ) 95 | 96 | rticles_opts <- purrr::discard(rticles_opts, is_yml_blank) 97 | 98 | warn_if_duplicate_fields(.yml, rticles_opts) 99 | .yml[names(rticles_opts)] <- rticles_opts 100 | 101 | .yml 102 | } 103 | 104 | #' @param name The author's name 105 | #' @param num The author's number or address number 106 | #' 107 | #' @export 108 | #' @rdname yml_rticles_opts 109 | rticles_author <- function(name = yml_blank(), num = yml_blank()) { 110 | list( 111 | name = name, 112 | num = num 113 | ) %>% 114 | purrr::discard(is_yml_blank) 115 | } 116 | 117 | #' @param org The author's organization 118 | #' 119 | #' @export 120 | #' @rdname yml_rticles_opts 121 | rticles_address <- function(name = yml_blank(), org = yml_blank()) { 122 | list( 123 | name = name, 124 | org = org 125 | ) %>% 126 | purrr::discard(is_yml_blank) 127 | } 128 | 129 | 130 | #' @export 131 | #' @rdname yml_rticles_opts 132 | rticles_corr_author <- function(name = yml_blank(), author = yml_blank(), address = yml_blank()) { 133 | list( 134 | name = name, 135 | author = author, 136 | address = address 137 | ) %>% 138 | purrr::discard(is_yml_blank) 139 | } 140 | -------------------------------------------------------------------------------- /man/yml_site_opts.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_rmarkdown.R 3 | \name{yml_site_opts} 4 | \alias{yml_site_opts} 5 | \alias{yml_navbar} 6 | \alias{navbar_page} 7 | \alias{navbar_separator} 8 | \title{Add site options for \verb{_site.yml} and navbars for R Markdown websites} 9 | \usage{ 10 | yml_site_opts( 11 | .yml, 12 | name = yml_blank(), 13 | favicon = yml_blank(), 14 | output_dir = yml_blank(), 15 | include = yml_blank(), 16 | exclude = yml_blank(), 17 | new_session = yml_blank(), 18 | ... 19 | ) 20 | 21 | yml_navbar( 22 | .yml, 23 | title = yml_blank(), 24 | type = yml_blank(), 25 | left = yml_blank(), 26 | right = yml_blank(), 27 | ... 28 | ) 29 | 30 | navbar_page( 31 | text = yml_blank(), 32 | href = yml_blank(), 33 | icon = yml_blank(), 34 | menu = yml_blank(), 35 | ... 36 | ) 37 | 38 | navbar_separator() 39 | } 40 | \arguments{ 41 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 42 | a \verb{yml_*()} function} 43 | 44 | \item{name}{The name of the website} 45 | 46 | \item{favicon}{Path to a file to use as the favicon} 47 | 48 | \item{output_dir}{Directory to copy site content into ("_site" is the default 49 | if none is specified)} 50 | 51 | \item{include, exclude}{Files to include or exclude from the copied into 52 | \code{output_dir}. You can use \code{*} to indicate a wildcard selection, e.g. 53 | "*.csv".} 54 | 55 | \item{new_session}{Logical. Should each website file be rendered in a new 56 | R session?} 57 | 58 | \item{...}{additional named R objects, such as characters or lists, to 59 | transform into YAML} 60 | 61 | \item{title}{The title of the website} 62 | 63 | \item{type}{The color scheme for the navigation bar: either "default" or "inverse".} 64 | 65 | \item{left, right}{the side of the navbar a \code{navbar_page()} should go (see example)} 66 | 67 | \item{text}{The link text} 68 | 69 | \item{href}{The link URL} 70 | 71 | \item{icon}{An icon to include} 72 | 73 | \item{menu}{drop-down menus specified by including another \code{navbar_page()}} 74 | } 75 | \value{ 76 | a \code{yml} object 77 | } 78 | \description{ 79 | R Markdown has a simple website builder baked in (see the R \href{https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#site_navigation}{Markdown book} 80 | for a detailed description). An R Markdown website must have at least have an 81 | \code{index.Rmd} file and a \verb{_site.yml} file (which can be empty). Including YAML 82 | in \verb{_site.yml} will apply it to all R Markdown files for the website, e.g. 83 | setting the output format here will tell R Markdown to use that format across 84 | the website. R Markdown websites also support navbars, which you can specify 85 | with YAML (see \code{\link[=yml_navbar]{yml_navbar()}}, as well as ?rmarkdown::render_site and 86 | ?rmarkdown::html_document). Pass \code{navbar_page()} to the \code{left} or \code{right} 87 | field to set up page tabs and use \code{navbar_separator()} to include a 88 | separators. In addition to writing YAML with \verb{yml_*()} functions, 89 | \code{use_site_yml()} will take the a \code{yml} object and write it to a \verb{_site.yml} 90 | file for you. 91 | } 92 | \examples{ 93 | yml_empty() \%>\% 94 | yml_site_opts( 95 | name = "my-website", 96 | output_dir = "_site", 97 | include = "demo.R", 98 | exclude = c("docs.txt", "*.csv") 99 | ) \%>\% 100 | yml_navbar( 101 | title = "My Website", 102 | left = list( 103 | navbar_page("Home", href = "index.html"), 104 | navbar_page(navbar_separator(), href = "about.html") 105 | ) 106 | ) \%>\% 107 | yml_output(html_document(toc = TRUE, highlight = "textmate")) 108 | 109 | } 110 | \seealso{ 111 | \code{\link[=use_site_yml]{use_site_yml()}} \code{\link[=use_navbar_yml]{use_navbar_yml()}} \code{\link[=use_index_rmd]{use_index_rmd()}} 112 | 113 | Other yml: 114 | \code{\link{asis_yaml_output}()}, 115 | \code{\link{bib2yml}()}, 116 | \code{\link{draw_yml_tree}()}, 117 | \code{\link{has_field}()}, 118 | \code{\link{read_json}()}, 119 | \code{\link{use_yml_defaults}()}, 120 | \code{\link{use_yml_file}()}, 121 | \code{\link{use_yml}()}, 122 | \code{\link{yml_author}()}, 123 | \code{\link{yml_blogdown_opts}()}, 124 | \code{\link{yml_bookdown_opts}()}, 125 | \code{\link{yml_citations}()}, 126 | \code{\link{yml_clean}()}, 127 | \code{\link{yml_distill_opts}()}, 128 | \code{\link{yml_latex_opts}()}, 129 | \code{\link{yml_output}()}, 130 | \code{\link{yml_pagedown_opts}()}, 131 | \code{\link{yml_params}()}, 132 | \code{\link{yml_pkgdown}()}, 133 | \code{\link{yml_reference}()}, 134 | \code{\link{yml_replace}()}, 135 | \code{\link{yml_resource_files}()}, 136 | \code{\link{yml_rsconnect_email}()}, 137 | \code{\link{yml_rticles_opts}()}, 138 | \code{\link{yml_runtime}()}, 139 | \code{\link{yml_toc}()}, 140 | \code{\link{yml_vignette}()} 141 | 142 | Other R Markdown: 143 | \code{\link{yml_clean}()}, 144 | \code{\link{yml_params}()}, 145 | \code{\link{yml_runtime}()}, 146 | \code{\link{yml_vignette}()} 147 | 148 | Other websites: 149 | \code{\link{yml_distill_opts}()}, 150 | \code{\link{yml_pkgdown}()} 151 | } 152 | \concept{R Markdown} 153 | \concept{websites} 154 | \concept{yml} 155 | -------------------------------------------------------------------------------- /man/yml_rticles_opts.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_rticles.R 3 | \name{yml_rticles_opts} 4 | \alias{yml_rticles_opts} 5 | \alias{rticles_author} 6 | \alias{rticles_address} 7 | \alias{rticles_corr_author} 8 | \title{Set YAML related to rticles output formats} 9 | \usage{ 10 | yml_rticles_opts( 11 | .yml, 12 | title = yml_blank(), 13 | runninghead = yml_blank(), 14 | author = yml_blank(), 15 | authormark = yml_blank(), 16 | address = yml_blank(), 17 | corrauth = yml_blank(), 18 | corres = yml_blank(), 19 | email = yml_blank(), 20 | abstract = yml_blank(), 21 | received = yml_blank(), 22 | revised = yml_blank(), 23 | accepted = yml_blank(), 24 | keywords = yml_blank(), 25 | bibliography = yml_blank(), 26 | longtable = yml_blank(), 27 | classoption = yml_blank(), 28 | header_includes = yml_blank(), 29 | include_after = yml_blank(), 30 | ... 31 | ) 32 | 33 | rticles_author(name = yml_blank(), num = yml_blank()) 34 | 35 | rticles_address(name = yml_blank(), org = yml_blank()) 36 | 37 | rticles_corr_author( 38 | name = yml_blank(), 39 | author = yml_blank(), 40 | address = yml_blank() 41 | ) 42 | } 43 | \arguments{ 44 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 45 | a \verb{yml_*()} function} 46 | 47 | \item{title}{Title of the manuscript} 48 | 49 | \item{runninghead}{A character vector, a short author list for the header 50 | (sage_article)} 51 | 52 | \item{author}{A list of authors, containing \code{name} and \code{num} fields 53 | (sage_article, sim_article). Use \code{rticles_author()} or a list to specify.} 54 | 55 | \item{authormark}{A character vector, the short author list for the header 56 | (sim_article)} 57 | 58 | \item{address}{list containing \code{num} and \code{org} for defining author 59 | affiliations (sage_article, sim_article). Use \code{rticles_address()} or a list 60 | to specify.} 61 | 62 | \item{corrauth}{corresponding author \code{name} and \code{address} (sage_article). Use 63 | \code{rticles_corr_author()} or a list to specify.} 64 | 65 | \item{corres}{\code{author} and \code{address} for correspondence (sim_article). Use 66 | \code{rticles_corr_author()} or a list to specify.} 67 | 68 | \item{email}{The email of the correspondence author (sage_article)} 69 | 70 | \item{abstract}{The abstract, limited to 200 words (sage_article), 250 words 71 | (sim_article)} 72 | 73 | \item{received, revised, accepted}{The dates of submission, revision, and 74 | acceptance of the manuscript (sim_article)} 75 | 76 | \item{keywords}{The keywords for the article (sage_article), up to 6 keywords 77 | (sim_article)} 78 | 79 | \item{bibliography}{BibTeX \code{.bib} file name (sage_article, sim_article)} 80 | 81 | \item{longtable}{Logical. Include the longtable package? Used by default from 82 | pandoc to convert markdown to LaTeX code (sim_article)} 83 | 84 | \item{classoption}{a character vector of \code{classoption} options for the 85 | \code{sagej} class (sage_article)} 86 | 87 | \item{header_includes}{additional LaTeX code to include in the header, before 88 | the \verb{\\\\begin\\\{document\\\}} statement (sage_article, sim_article). Note that 89 | the actual YAML field is \code{header-includes}} 90 | 91 | \item{include_after}{additional LaTeX code to include before the 92 | \verb{\\\\end\\\{document\\\}} statement (sage_article, sim_article). Note that the 93 | actual YAML field is \code{include-after}.} 94 | 95 | \item{...}{additional named R objects, such as characters or lists, to 96 | transform into YAML} 97 | 98 | \item{name}{The author's name} 99 | 100 | \item{num}{The author's number or address number} 101 | 102 | \item{org}{The author's organization} 103 | } 104 | \value{ 105 | a \code{yml} object 106 | } 107 | \description{ 108 | The rticles package include numerous output formats specific to academic 109 | journals. All of these can take YAML similar to \code{pdf_document()}. 110 | Additionally, two templates include custom YAML, \code{rticles::sage_article()} 111 | and \code{rticles::sim_article()}. See the help pages for these functions for more 112 | details and the sources of the LaTeX templates used for each. 113 | } 114 | \examples{ 115 | 116 | yml() \%>\% 117 | yml_rticles_opts(received = "09-12-2014") 118 | 119 | } 120 | \seealso{ 121 | Other yml: 122 | \code{\link{asis_yaml_output}()}, 123 | \code{\link{bib2yml}()}, 124 | \code{\link{draw_yml_tree}()}, 125 | \code{\link{has_field}()}, 126 | \code{\link{read_json}()}, 127 | \code{\link{use_yml_defaults}()}, 128 | \code{\link{use_yml_file}()}, 129 | \code{\link{use_yml}()}, 130 | \code{\link{yml_author}()}, 131 | \code{\link{yml_blogdown_opts}()}, 132 | \code{\link{yml_bookdown_opts}()}, 133 | \code{\link{yml_citations}()}, 134 | \code{\link{yml_clean}()}, 135 | \code{\link{yml_distill_opts}()}, 136 | \code{\link{yml_latex_opts}()}, 137 | \code{\link{yml_output}()}, 138 | \code{\link{yml_pagedown_opts}()}, 139 | \code{\link{yml_params}()}, 140 | \code{\link{yml_pkgdown}()}, 141 | \code{\link{yml_reference}()}, 142 | \code{\link{yml_replace}()}, 143 | \code{\link{yml_resource_files}()}, 144 | \code{\link{yml_rsconnect_email}()}, 145 | \code{\link{yml_runtime}()}, 146 | \code{\link{yml_site_opts}()}, 147 | \code{\link{yml_toc}()}, 148 | \code{\link{yml_vignette}()} 149 | } 150 | \concept{yml} 151 | -------------------------------------------------------------------------------- /vignettes/yaml-fieldguide.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "The YAML Fieldguide" 3 | output: 4 | prettydoc::html_pretty: 5 | theme: tactile 6 | vignette: > 7 | %\VignetteIndexEntry{The YAML Fieldguide} 8 | %\VignetteEngine{knitr::rmarkdown} 9 | %\VignetteEncoding{UTF-8} 10 | --- 11 | 12 | ```{r, include = FALSE} 13 | knitr::opts_chunk$set( 14 | echo = FALSE, 15 | message = FALSE, 16 | collapse = TRUE, 17 | comment = "", 18 | warning = FALSE 19 | ) 20 | ``` 21 | 22 | 23 | ```{r pandoc_check, echo=FALSE} 24 | if (!rmarkdown::pandoc_available()) { 25 | cat("pandoc is required to use ymlthis. Please visit https://pandoc.org/ for more information.") 26 | knitr::knit_exit() 27 | } 28 | ``` 29 | 30 | 31 | ```{r roxygen_check, echo=FALSE} 32 | if (!requireNamespace("roxygen2")) { 33 | cat("roxygen2 is required to render this vignette: `install.packages('roxygen2'`") 34 | knitr::knit_exit() 35 | } 36 | ``` 37 | 38 | ```{r setup} 39 | library(ymlthis) 40 | oldoption <- options(devtools.name = "Malcolm Barrett", crayon.enabled = FALSE) 41 | 42 | function_name <- function(x) { 43 | function_call <- x$call 44 | ifelse(rlang::has_length(function_call), as.character(function_call[[2]]), NA) 45 | } 46 | 47 | block_names <- function(x) x$tags %>% purrr::map_chr(~.x$tag) 48 | 49 | get_doc_name <- function(x) { 50 | tags <- block_names(x) 51 | rdname_index <- which(tags == "rdname") 52 | if (purrr::is_empty(rdname_index)) return(function_name(x)) 53 | 54 | x$tags[[rdname_index]]$val 55 | } 56 | 57 | get_params <- function(x) { 58 | param_lists <- which(block_names(x) == "param") 59 | f <- get_doc_name(x) 60 | if (!rlang::has_length(param_lists) || is.na(f)) return(data.frame()) 61 | 62 | params_desc <- x$tags[param_lists] %>% 63 | purrr::map(~as.data.frame(.x$val, stringsAsFactors = FALSE)) %>% 64 | do.call(rbind, .) 65 | 66 | params_desc$description <- stringr::str_replace_all( 67 | params_desc$description, 68 | "\n", 69 | " " 70 | ) 71 | 72 | params_desc$name <- params_desc$name %>% 73 | stringr::str_split(",") %>% 74 | purrr::map_chr( 75 | ~paste0("`", .x, "`") %>% paste(collapse = ", ") 76 | ) 77 | 78 | cbind(func = f, params_desc, stringsAsFactors = FALSE) 79 | } 80 | 81 | link_help_page <- function(x) { 82 | url <- "https://ymlthis.r-lib.org/" 83 | glue::glue("{x}") 84 | } 85 | 86 | filter_kable <- function(.tbl, .pattern = NULL, caption = NULL) { 87 | if (!is.null(.pattern)) { 88 | index <- stringr::str_detect(.tbl$func, .pattern) 89 | .tbl <- .tbl[index, ] 90 | } 91 | .tbl$func <- link_help_page(.tbl$func) 92 | 93 | knitr::kable( 94 | .tbl, 95 | col.names = c("Help Page", "Argument", "Description"), 96 | row.names = FALSE, 97 | caption = caption 98 | ) 99 | } 100 | 101 | fields_df <- roxygen2::parse_package("../") %>% 102 | purrr::map(get_params) %>% 103 | do.call(rbind, .) 104 | ``` 105 | 106 | **ymlthis** attempts to write common YAML for you in the right way and to document the many YAML field options in one place. The fieldguide is a collection of all the fields documented in the **ymlthis** help pages, organized by source. Note that some argument names do not match the YAML field name exactly in order because not all field names are valid R names (e.g. the `link-citations` YAML field needs to be `link_citations` in R); these differences are noted in the argument description. Additionally, not all of these arguments are top-level YAML; see the linked help pages for more details. 107 | 108 | ## Basic YAML 109 | 110 | ```{r} 111 | fields_df %>% 112 | filter_kable("yml_author|yml_runtime|yml_clean|yml_toc", caption = "Basic YAML") 113 | ``` 114 | 115 | The nested fields for the `output` field are based on the arguments of the output function. See the help page for the function you are using, e.g., `?rmarkdown::pdf_document`. 116 | 117 | ## LaTeX/PDF Options 118 | 119 | ```{r} 120 | fields_df %>% 121 | filter_kable("latex", caption = "LaTeX/PDF Options") 122 | ``` 123 | 124 | ## R Markdown Websites 125 | 126 | ```{r} 127 | fields_df %>% 128 | filter_kable("site|navbar|vignette", caption = "R Markdown Websites") 129 | ``` 130 | 131 | ## Citations 132 | 133 | ```{r} 134 | fields_df %>% 135 | filter_kable("citations", caption = "Citations") 136 | ``` 137 | 138 | ## blogdown YAML 139 | 140 | ```{r} 141 | fields_df %>% 142 | filter_kable("yml_blogdown_opts", caption = "blogdown YAML") 143 | ``` 144 | 145 | ## bookdown YAML 146 | 147 | ```{r} 148 | fields_df %>% 149 | filter_kable("bookdown", caption = "bookdown YAML") 150 | ``` 151 | 152 | ## pkgdown YAML 153 | 154 | ```{r} 155 | fields_df %>% 156 | filter_kable("yml_pkgdown", caption = "pkgdown YAML") 157 | ``` 158 | 159 | ## pagedown YAML 160 | 161 | ```{r} 162 | fields_df %>% 163 | filter_kable("pagedown", caption = "pagedown YAML") 164 | ``` 165 | 166 | ## distill YAML 167 | 168 | ```{r} 169 | fields_df %>% 170 | filter_kable("distill", caption = "distill YAML") 171 | ``` 172 | 173 | ## rticles YAML 174 | 175 | ```{r} 176 | fields_df %>% 177 | filter_kable("rticles", caption = "rticles YAML") 178 | ``` 179 | 180 | ## RStudio Connect Scheduled Email YAML 181 | 182 | ```{r} 183 | fields_df %>% 184 | filter_kable("rsconnect", caption = "RStudio Connect Scheduled Email YAML") 185 | ``` 186 | 187 | ```{r, include=FALSE} 188 | options(oldoption) 189 | ``` 190 | -------------------------------------------------------------------------------- /man/yml_bookdown_opts.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_bookdown.R 3 | \name{yml_bookdown_opts} 4 | \alias{yml_bookdown_opts} 5 | \alias{yml_bookdown_site} 6 | \title{Set Top-level YAML options for bookdown} 7 | \usage{ 8 | yml_bookdown_opts( 9 | .yml, 10 | book_filename = yml_blank(), 11 | delete_merged_file = yml_blank(), 12 | before_chapter_script = yml_blank(), 13 | after_chapter_script = yml_blank(), 14 | edit = yml_blank(), 15 | history = yml_blank(), 16 | rmd_files = yml_blank(), 17 | rmd_subdir = yml_blank(), 18 | output_dir = yml_blank(), 19 | clean = yml_blank(), 20 | ... 21 | ) 22 | 23 | yml_bookdown_site(.yml) 24 | } 25 | \arguments{ 26 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 27 | a \verb{yml_*()} function} 28 | 29 | \item{book_filename}{A character vector, the filename of the main \code{.Rmd} 30 | file, the \code{.Rmd} file that is created by merging all chapters. By default, 31 | it is called "_main.Rmd".} 32 | 33 | \item{delete_merged_file}{Logical. Delete the main \code{.Rmd} file if it exists?} 34 | 35 | \item{before_chapter_script, after_chapter_script}{A character vector of one 36 | or more R scripts to be executed before or after each chapter} 37 | 38 | \item{edit}{A URL that collaborators can click to edit the \code{.Rmd} source 39 | document of the current page, usually a link to a GitHub repository. This 40 | link should have \verb{\%s} where the actual \code{.Rmd} filename for each page will 41 | go.} 42 | 43 | \item{history}{Similar to \code{edit}, a link to the edit/commit history of the 44 | current page.} 45 | 46 | \item{rmd_files}{A character vector, the order order of \code{.Rmd} files for the 47 | book. \code{rmd_files} can also be a named list where each element of the list 48 | is named for the output type, e.g. "html" or "latex". By default, bookdown 49 | merges all \code{.Rmd} files by the order of filenames.} 50 | 51 | \item{rmd_subdir}{whether to search for book source \code{.Rmd} files in 52 | subdirectories (by default, only the root directory is searched). This may 53 | be either a boolean (e.g. \code{TRUE} will search for book source \code{.Rmd} files 54 | in the project directory and all subdirectories) or vector of paths if you 55 | want to search for book source \code{.Rmd} files in a subset of subdirectories.} 56 | 57 | \item{output_dir}{the output directory of the book ("_book" by default)} 58 | 59 | \item{clean}{a character vector of files and directories to be cleaned by the 60 | \code{bookdown::clean_book()} function.} 61 | 62 | \item{...}{additional named R objects, such as characters or lists, to 63 | transform into YAML} 64 | } 65 | \value{ 66 | a \code{yml} object 67 | } 68 | \description{ 69 | bookdown uses YAML in three main places, as described in the \href{https://bookdown.org/yihui/rmarkdown/bookdown-project.html}{bookdown book}: 70 | \code{index.Rmd}, \verb{_output.yml}, and \verb{_bookdown.yml}. \code{index.Rmd} can take most 71 | YAML. \verb{_output.yml} is intended for output-related YAML, such as that 72 | produced by \code{yml() \%>\% yml_output(bookdown::pdf_book())}. \verb{_bookdown.yml} is 73 | intended for configuring the build of the book. Pass the results of the 74 | \verb{yml_*()} functions to \code{use_index_rmd()}, \code{use_bookdown_yml()}, 75 | \code{use_output_yml()} to write them to these files. \code{yml_bookdown_site()} adds 76 | the \code{site: "bookdown::bookdown_site"} to the YAML metadata. 77 | } 78 | \examples{ 79 | 80 | yml_empty() \%>\% 81 | yml_bookdown_opts( 82 | book_filename = "my-book.Rmd", 83 | before_chapter_script = c("script1.R", "script2.R"), 84 | after_chapter_script = "script3.R", 85 | edit = "https =//github.com/rstudio/bookdown-demo/edit/master/\%s", 86 | output_dir = "book-output", 87 | clean = c("my-book.bbl", "R-packages.bib") 88 | ) 89 | 90 | yml_empty() \%>\% 91 | yml_bookdown_opts( 92 | rmd_files = list( 93 | html = c("index.Rmd", "abstract.Rmd", "intro.Rmd"), 94 | latex = c("abstract.Rmd", "intro.Rmd") 95 | ) 96 | ) 97 | 98 | x <- yml_empty() \%>\% 99 | yml_title("A Minimal Book Example") \%>\% 100 | yml_date(yml_code(Sys.Date())) \%>\% 101 | yml_author("Yihui Xie") \%>\% 102 | yml_bookdown_site() \%>\% 103 | yml_latex_opts( 104 | documentclass = "book", 105 | bibliography = c("book.bib", "packages.bib"), 106 | biblio_style = "apalike" 107 | ) \%>\% 108 | yml_citations( 109 | link_citations = TRUE 110 | ) \%>\% 111 | yml_description("This is a minimal example of using 112 | the bookdown package to write a book.") 113 | 114 | x 115 | 116 | 117 | \donttest{ 118 | output_yml <- yml_empty() \%>\% 119 | yml_output( 120 | bookdown::gitbook( 121 | lib_dir = "assets", 122 | split_by = "section", 123 | config = gitbook_config(toolbar_position = "static") 124 | ), 125 | bookdown::pdf_book(keep_tex = TRUE), 126 | bookdown::html_book(css = "toc.css") 127 | ) 128 | output_yml 129 | } 130 | 131 | 132 | } 133 | \seealso{ 134 | \code{\link[=use_index_rmd]{use_index_rmd()}} \code{\link[=use_bookdown_yml]{use_bookdown_yml()}} \code{\link[=use_output_yml]{use_output_yml()}} 135 | 136 | Other yml: 137 | \code{\link{asis_yaml_output}()}, 138 | \code{\link{bib2yml}()}, 139 | \code{\link{draw_yml_tree}()}, 140 | \code{\link{has_field}()}, 141 | \code{\link{read_json}()}, 142 | \code{\link{use_yml_defaults}()}, 143 | \code{\link{use_yml_file}()}, 144 | \code{\link{use_yml}()}, 145 | \code{\link{yml_author}()}, 146 | \code{\link{yml_blogdown_opts}()}, 147 | \code{\link{yml_citations}()}, 148 | \code{\link{yml_clean}()}, 149 | \code{\link{yml_distill_opts}()}, 150 | \code{\link{yml_latex_opts}()}, 151 | \code{\link{yml_output}()}, 152 | \code{\link{yml_pagedown_opts}()}, 153 | \code{\link{yml_params}()}, 154 | \code{\link{yml_pkgdown}()}, 155 | \code{\link{yml_reference}()}, 156 | \code{\link{yml_replace}()}, 157 | \code{\link{yml_resource_files}()}, 158 | \code{\link{yml_rsconnect_email}()}, 159 | \code{\link{yml_rticles_opts}()}, 160 | \code{\link{yml_runtime}()}, 161 | \code{\link{yml_site_opts}()}, 162 | \code{\link{yml_toc}()}, 163 | \code{\link{yml_vignette}()} 164 | 165 | Other bookdown: 166 | \code{\link{gitbook_config}()} 167 | } 168 | \concept{bookdown} 169 | \concept{yml} 170 | -------------------------------------------------------------------------------- /man/yml_author.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_top.R 3 | \name{yml_author} 4 | \alias{yml_author} 5 | \alias{yml_date} 6 | \alias{yml_title} 7 | \alias{yml_subtitle} 8 | \alias{yml_abstract} 9 | \alias{yml_keywords} 10 | \alias{yml_subject} 11 | \alias{yml_description} 12 | \alias{yml_category} 13 | \alias{yml_lang} 14 | \alias{yml_toplevel} 15 | \title{Set Top-level R Markdown YAML Fields} 16 | \usage{ 17 | yml_author(.yml, name = NULL, affiliation = NULL, email = NULL, ...) 18 | 19 | yml_date(.yml, date = NULL, format = "") 20 | 21 | yml_title(.yml, title) 22 | 23 | yml_subtitle(.yml, subtitle) 24 | 25 | yml_abstract(.yml, abstract) 26 | 27 | yml_keywords(.yml, keywords) 28 | 29 | yml_subject(.yml, subject) 30 | 31 | yml_description(.yml, description) 32 | 33 | yml_category(.yml, category) 34 | 35 | yml_lang(.yml, lang) 36 | 37 | yml_toplevel(.yml, ...) 38 | } 39 | \arguments{ 40 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 41 | a \verb{yml_*()} function} 42 | 43 | \item{name}{A character vector, name of the author(s)} 44 | 45 | \item{affiliation}{The author's affiliation; must match length of \code{name}, 46 | e.g. if \code{name} has length of two, \code{affiliation} must as well; use \code{NA} if 47 | you don't want to include an affiliation for a given author.Note that not 48 | all formats support the \code{affiliation} field.} 49 | 50 | \item{email}{The author email address. Note that not all formats support the 51 | \code{email} field.} 52 | 53 | \item{...}{additional named R objects, such as characters or lists, to 54 | transform into YAML} 55 | 56 | \item{date}{The date; by default this is "\code{`r format(Sys.Date())`}", 57 | which will populate the date automatically.} 58 | 59 | \item{format}{When the default \code{date} is used, the format passed to 60 | \code{\link[=format.Date]{format.Date()}}.} 61 | 62 | \item{title}{A character vector, the title of the document} 63 | 64 | \item{subtitle}{A character vector, the subtitle of the document. Not all R 65 | Markdown formats use subtitles, so it may depend on what you use in the 66 | output field (see \code{\link[=yml_output]{yml_output()}}). It is available in \code{pdf_document()}, 67 | \code{html_document()}, and \code{word_document()} by default.} 68 | 69 | \item{abstract}{A character vector, the abstract. Long character vectors are 70 | automatically wrapped using valid YAML syntax. This field is not available 71 | in all output formats; it is available in \code{pdf_document()} and 72 | \code{html_document()} by default.} 73 | 74 | \item{keywords}{A character vector of keywords. This field is not available 75 | in all output formats; it is available in \code{pdf_document()}, 76 | \code{html_document()}, \code{word_document()}, \code{odt_document()}, and 77 | \code{powerpoint_presentation()} by default.} 78 | 79 | \item{subject}{A character vector, the subject of the document. This field is 80 | not available in all output formats; it is available in \code{pdf_document()}, 81 | \code{html_document()}, \code{word_document()}, \code{odt_document()}, and 82 | \code{powerpoint_presentation()} by default.} 83 | 84 | \item{description}{A character vector, a description of the document. This 85 | field is not available in all output formats; it is available in 86 | \code{word_document()}, \code{odt_document()}, and \code{powerpoint_presentation()} by 87 | default.} 88 | 89 | \item{category}{A character vector, the category of the document. This field 90 | is not available in all output formats; it is available in 91 | \code{word_document()} and \code{powerpoint_presentation()} by default.} 92 | 93 | \item{lang}{The document language using IETF language tags such as "en" or 94 | "en-US". The \href{https://r12a.github.io/app-subtags/}{Language subtag lookup tool} can help find the appropriate 95 | tag.} 96 | } 97 | \value{ 98 | a \code{yml} object 99 | } 100 | \description{ 101 | These functions add common top-level YAML fields for R Markdown documents, 102 | such as \code{author}, \code{date}, and \code{title}. Each takes a \code{yml} object and adds 103 | fields related to the function, as well as checking for duplicate fields and 104 | (where possible) checking for valid entries. \code{yml_toplevel()} is a catch-all 105 | function that will take any named R object and put in the top level of the 106 | YAML; it checks for duplicate fields but is unable to validate the input 107 | beyond that it is valid YAML syntax. Some R Markdown templates allow for 108 | additional variations of the YAML here. For instance, the distill package 109 | adds \code{url} and \code{affiliation_url} to the \code{author} field (see 110 | \link{yml_distill_author}, which wraps \link{yml_author}). Several \verb{yml_*()} functions 111 | also contain \code{...} which allow for these unique fields. 112 | } 113 | \examples{ 114 | yml_empty() \%>\% 115 | yml_author("Yihui Xie") \%>\% 116 | yml_date("02-02-2002") \%>\% 117 | yml_title("R Markdown: An Introduction") \%>\% 118 | yml_subtitle("Introducing ymlthis") \%>\% 119 | yml_abstract("This paper will discuss a very important topic") \%>\% 120 | yml_keywords(c("r", "reproducible research")) \%>\% 121 | yml_subject("R Markdown") \%>\% 122 | yml_description("An R Markdown reader") \%>\% 123 | yml_category("r") \%>\% 124 | yml_lang("en-US") 125 | 126 | } 127 | \seealso{ 128 | Other yml: 129 | \code{\link{asis_yaml_output}()}, 130 | \code{\link{bib2yml}()}, 131 | \code{\link{draw_yml_tree}()}, 132 | \code{\link{has_field}()}, 133 | \code{\link{read_json}()}, 134 | \code{\link{use_yml_defaults}()}, 135 | \code{\link{use_yml_file}()}, 136 | \code{\link{use_yml}()}, 137 | \code{\link{yml_blogdown_opts}()}, 138 | \code{\link{yml_bookdown_opts}()}, 139 | \code{\link{yml_citations}()}, 140 | \code{\link{yml_clean}()}, 141 | \code{\link{yml_distill_opts}()}, 142 | \code{\link{yml_latex_opts}()}, 143 | \code{\link{yml_output}()}, 144 | \code{\link{yml_pagedown_opts}()}, 145 | \code{\link{yml_params}()}, 146 | \code{\link{yml_pkgdown}()}, 147 | \code{\link{yml_reference}()}, 148 | \code{\link{yml_replace}()}, 149 | \code{\link{yml_resource_files}()}, 150 | \code{\link{yml_rsconnect_email}()}, 151 | \code{\link{yml_rticles_opts}()}, 152 | \code{\link{yml_runtime}()}, 153 | \code{\link{yml_site_opts}()}, 154 | \code{\link{yml_toc}()}, 155 | \code{\link{yml_vignette}()} 156 | } 157 | \concept{yml} 158 | -------------------------------------------------------------------------------- /man/yml_blogdown_opts.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/yml_blogdown.R 3 | \name{yml_blogdown_opts} 4 | \alias{yml_blogdown_opts} 5 | \title{Set Top-level YAML options for blogdown} 6 | \usage{ 7 | yml_blogdown_opts( 8 | .yml, 9 | draft = yml_blank(), 10 | publishdate = yml_blank(), 11 | weight = yml_blank(), 12 | slug = yml_blank(), 13 | aliases = yml_blank(), 14 | audio = yml_blank(), 15 | date = yml_blank(), 16 | description = yml_blank(), 17 | expiration_date = yml_blank(), 18 | headless = yml_blank(), 19 | images = yml_blank(), 20 | keywords = yml_blank(), 21 | layout = yml_blank(), 22 | lastmod = yml_blank(), 23 | link_title = yml_blank(), 24 | resources = yml_blank(), 25 | series = yml_blank(), 26 | summary = yml_blank(), 27 | title = yml_blank(), 28 | type = yml_blank(), 29 | url = yml_blank(), 30 | videos = yml_blank(), 31 | ... 32 | ) 33 | } 34 | \arguments{ 35 | \item{.yml}{a \code{yml} object created by \code{yml()}, \code{as_yml()}, or returned by 36 | a \verb{yml_*()} function} 37 | 38 | \item{draft}{Logical. Set post as a draft? Draft posts will not be rendered 39 | if the site is built via \code{blogdown::build_site()} or 40 | \code{blogdown::hugo_build()} but will be rendered in the local preview mode. 41 | See \href{https://bookdown.org/yihui/blogdown/local-preview.html#local-preview}{Section D.3 of the blogdown book}.} 42 | 43 | \item{publishdate}{A future date to publish the post. Future posts are only 44 | rendered in the local preview mode} 45 | 46 | \item{weight}{This field can take a numeric value to tell Hugo the order of 47 | pages when sorting them, e.g., when you generate a list of all pages under 48 | a directory, and two posts have the same date, you may assign different 49 | weights to them to get your desired order on the list} 50 | 51 | \item{slug}{A character string used as the tail of the post URL. It is 52 | particularly useful when you define custom rules for permanent URLs. See 53 | \href{https://bookdown.org/yihui/blogdown/configuration.html#options}{Section 2.2.2 of the blogdown book}.} 54 | 55 | \item{aliases}{A character vector of one or more aliases (e.g., old published 56 | paths of renamed content) that will be created in the output directory 57 | structure} 58 | 59 | \item{audio}{A character vector of paths to audio files related to the page} 60 | 61 | \item{date}{The date assigned to this page. This is usually fetched from the 62 | \code{date} field in front matter, but this behavior is configurable.} 63 | 64 | \item{description}{The description for the content} 65 | 66 | \item{expiration_date}{the date at which the content should no longer be 67 | published by Hugo. Note that the actual YAML field is \code{expiryDate}} 68 | 69 | \item{headless}{if \code{TRUE}, sets a leaf bundle to be 70 | \href{https://gohugo.io/content-management/page-bundles/#headless-bundle}{headless}.} 71 | 72 | \item{images}{A character vector of paths to images related to the page} 73 | 74 | \item{keywords}{A character vector of the keywords for the content.} 75 | 76 | \item{layout}{The layout Hugo should use while rendering the content. By 77 | default, \code{layout} matches \code{type} and is thus based on the directory. 78 | However, it's possible to use additional layouts within a type. See \href{https://gohugo.io/content-management/types/#defining-a-content-type}{Hugo's Defining a Content Type documentation}.} 79 | 80 | \item{lastmod}{The date the content was last modified at} 81 | 82 | \item{link_title}{used for creating links to content. Note that the actual 83 | YAML field is \code{linkTitle}} 84 | 85 | \item{resources}{A named list. Used for configuring page bundle resources. 86 | See \href{https://gohugo.io/content-management/page-resources/}{Hugo's Page Resources documentation}} 87 | 88 | \item{series}{A character vector of series this page belongs to} 89 | 90 | \item{summary}{A summary of the content in the \code{.Summary} Hugo page variable; 91 | see the 92 | \href{https://gohugo.io/content-management/summaries/}{content-summaries} 93 | section of Hugo's documentation.} 94 | 95 | \item{title}{The title for the content} 96 | 97 | \item{type}{The type of the content, which is based on the from the directory 98 | of the content if not specified} 99 | 100 | \item{url}{The full path to the content from the web root} 101 | 102 | \item{videos}{A character vector of paths to videos related to the page} 103 | 104 | \item{...}{additional named R objects, such as characters or lists, to 105 | transform into YAML} 106 | } 107 | \value{ 108 | a \code{yml} object 109 | } 110 | \description{ 111 | YAML in blogdown comes from a variety of sources. Most YAML will be for your 112 | posts, as described in the \href{https://bookdown.org/yihui/blogdown/content.html#yaml-metadata}{blogdown book}). 113 | Common R Markdown fields can be used, but there are two other main sources 114 | for YAML fields: Hugo itself and the Hugo theme you are using. Hugo has 115 | numerous top-level YAML to control the output (see the \href{https://gohugo.io/content-management/front-matter/}{Hugo documentation}). 116 | \code{yml_blogdown_opts()} supports Hugo YAML. Your Hugo theme may also add fields 117 | to use. To find YAML specific to your theme, see \code{\link[=blogdown_template]{blogdown_template()}}. In 118 | addition to these sources of YAML, the configuration file for your blog can 119 | also be in YAML, but this is not very common; most use a \code{config.toml} file, 120 | based on TOML (see the \href{https://bookdown.org/yihui/blogdown/configuration.html}{blogdown book} for more). 121 | } 122 | \examples{ 123 | 124 | yml() \%>\% 125 | yml_blogdown_opts( 126 | draft = TRUE, 127 | slug = "blog-post" 128 | ) 129 | } 130 | \seealso{ 131 | Other yml: 132 | \code{\link{asis_yaml_output}()}, 133 | \code{\link{bib2yml}()}, 134 | \code{\link{draw_yml_tree}()}, 135 | \code{\link{has_field}()}, 136 | \code{\link{read_json}()}, 137 | \code{\link{use_yml_defaults}()}, 138 | \code{\link{use_yml_file}()}, 139 | \code{\link{use_yml}()}, 140 | \code{\link{yml_author}()}, 141 | \code{\link{yml_bookdown_opts}()}, 142 | \code{\link{yml_citations}()}, 143 | \code{\link{yml_clean}()}, 144 | \code{\link{yml_distill_opts}()}, 145 | \code{\link{yml_latex_opts}()}, 146 | \code{\link{yml_output}()}, 147 | \code{\link{yml_pagedown_opts}()}, 148 | \code{\link{yml_params}()}, 149 | \code{\link{yml_pkgdown}()}, 150 | \code{\link{yml_reference}()}, 151 | \code{\link{yml_replace}()}, 152 | \code{\link{yml_resource_files}()}, 153 | \code{\link{yml_rsconnect_email}()}, 154 | \code{\link{yml_rticles_opts}()}, 155 | \code{\link{yml_runtime}()}, 156 | \code{\link{yml_site_opts}()}, 157 | \code{\link{yml_toc}()}, 158 | \code{\link{yml_vignette}()} 159 | } 160 | \concept{yml} 161 | -------------------------------------------------------------------------------- /R/yml_pagedown.R: -------------------------------------------------------------------------------- 1 | #' Top-level YAML options for pagedown 2 | #' 3 | #' pagedown offers several output functions for paginated output, resumes, 4 | #' business cards, theses, and morem as described in the [pagedown 5 | #' vignette](https://pagedown.rbind.io/). pagedown also accepts a few custom 6 | #' top-level YAML. See [pagedown_business_card_template()] for more on setting 7 | #' up the YAML for a business card. 8 | #' 9 | #' @template describe_yml_param 10 | #' @param toc Logical. Use a table of contents? 11 | #' @param toc_title The title for the table of contents. Note that the actual 12 | #' YAML field is `toc-title` 13 | #' @param lot Logical. Use a list of figures? 14 | #' @param lot_title The title for the list of figures. Note that the actual YAML 15 | #' field is `lot-title` 16 | #' @param chapter_name The chapter title prefix 17 | #' @param links_to_footnotes Logical. Transform all the URLs to footnotes? Note 18 | #' that the actual YAML field is `links-to-footnotes` 19 | #' @param paged_footnotes Logical. Render notes as footnotes? Note that the 20 | #' actual YAML field is `paged-footnotes` 21 | #' 22 | #' @template describe_yml_output 23 | #' @export 24 | #' 25 | #' @examples 26 | #' 27 | #' yml() %>% 28 | #' yml_pagedown_opts( 29 | #' toc = TRUE, 30 | #' toc_title = "TOC", 31 | #' chapter_name = c("CHAPTER\\ ", "."), 32 | #' links_to_footnotes = TRUE 33 | #' ) 34 | #' 35 | #' @family pagedown 36 | yml_pagedown_opts <- function( 37 | .yml, 38 | toc = yml_blank(), 39 | toc_title = yml_blank(), 40 | lot = yml_blank(), 41 | lot_title = yml_blank(), 42 | chapter_name = yml_blank(), 43 | links_to_footnotes = yml_blank(), 44 | paged_footnotes = yml_blank() 45 | ) { 46 | pagedown_opts <- list( 47 | toc = toc, 48 | "toc-title" = toc_title, 49 | lot = lot, 50 | "lot-title" = lot_title, 51 | chapter_name = chapter_name, 52 | "links-to-footnotes" = links_to_footnotes, 53 | "paged-footnotes" = paged_footnotes 54 | ) %>% 55 | purrr::discard(is_yml_blank) 56 | 57 | warn_if_duplicate_fields(.yml, pagedown_opts) 58 | .yml[names(pagedown_opts)] <- pagedown_opts 59 | 60 | .yml 61 | } 62 | 63 | #' Generate a full YAML template for your pagedown business card 64 | #' 65 | #' pagedown has a unique output type to make business cards: 66 | #' `pagedown::business_card()`. `pagedown_business_card_template()` creates a 67 | #' YAML template to use for this output. What's unique about this output type is 68 | #' that almost all of the contents are supplied through YAML. An R Markdown file 69 | #' that only contains YAML related to the business card is enough to produce the 70 | #' output, although you can also customize the output in the body of the 71 | #' document (see the [pagedown vignette](https://pagedown.rbind.io/)). A good 72 | #' workflow to write a business card is to use 73 | #' `pagedown_business_card_template()` to specify the YAML and pass it to 74 | #' [use_rmarkdown()], which you can then to knit into business cards. 75 | #' 76 | #' @param name The name 77 | #' @param person When you are creating business cards for numerous people with 78 | #' shared information, passing values to the `person` field can override the 79 | #' default values, which can be any of the values accepted by this function. 80 | #' Use `pagedown_person()` to do so or manually provide them using `list(field 81 | #' = value)`. 82 | #' @param title The title of the person 83 | #' @param phone A phone number 84 | #' @param email An email address 85 | #' @param url A website URL 86 | #' @param address The address 87 | #' @param logo A path to a logo file 88 | #' @param .repeat The number of cards to repeat. Note that the actual YAML field 89 | #' is `repeat`. 90 | #' @param paperwidth The paper width 91 | #' @param paperheight The paper height 92 | #' @param cardwidth The width of the card 93 | #' @param cardheight The height of the card 94 | #' @param cols The number of columns in the card grid 95 | #' @param rows The rows of columns in the card grid 96 | #' @param mainfont The font 97 | #' @param googlefonts A character vector of Google Fonts 98 | #' @template describe_dots_param 99 | #' 100 | #' @template describe_yml_output 101 | #' @export 102 | #' 103 | #' @examples 104 | #' pagedown_business_card_template( 105 | #' name = "Jane Doe", 106 | #' title = "Miss Nobody", 107 | #' phone = "+1 123-456-7890", 108 | #' email = "jane.doe@example.com", 109 | #' url = "www.example.com", 110 | #' address = "2020 South Street, 111 | #' Sunshine, CA 90000", 112 | #' logo = "logo.png", 113 | #' .repeat = 12 114 | #' ) 115 | #' 116 | #' pagedown_business_card_template( 117 | #' phone = "+1 123-456-7890", 118 | #' url = "www.example.com", 119 | #' address = "2020 South Street, 120 | #' Sunshine, CA 90000", 121 | #' logo = "logo.png", 122 | #' person = list( 123 | #' pagedown_person( 124 | #' name = "Jane Doe", 125 | #' title = "Miss Nobody", 126 | #' email = "jane.doe@example.com", 127 | #' .repeat = 6 128 | #' ), 129 | #' pagedown_person( 130 | #' name = "John Doe", 131 | #' title = "Mister Nobody", 132 | #' phone = "+1 777-777-7777", # overrides the default phone 133 | #' email = "john.doe@example.com", 134 | #' .repeat = 6 135 | #' ) 136 | #' ), 137 | #' paperwidth = "8.5in", 138 | #' paperheight = "11in", 139 | #' cols = 4, 140 | #' rows = 3 141 | #' ) 142 | #' 143 | #' @seealso [`use_rmarkdown()`] 144 | #' @family pagedown 145 | pagedown_business_card_template <- function( 146 | name = yml_blank(), 147 | person = yml_blank(), 148 | title = yml_blank(), 149 | phone = yml_blank(), 150 | email = yml_blank(), 151 | url = yml_blank(), 152 | address = yml_blank(), 153 | logo = yml_blank(), 154 | .repeat = yml_blank(), 155 | paperwidth = yml_blank(), 156 | paperheight = yml_blank(), 157 | cardwidth = yml_blank(), 158 | cardheight = yml_blank(), 159 | cols = yml_blank(), 160 | rows = yml_blank(), 161 | mainfont = yml_blank(), 162 | googlefonts = yml_blank(), 163 | ... 164 | ) { 165 | list( 166 | name = name, 167 | person = person, 168 | title = title, 169 | phone = phone, 170 | email = email, 171 | url = url, 172 | address = address, 173 | logo = logo, 174 | "repeat" = .repeat, 175 | paperwidth = paperwidth, 176 | paperheight = paperheight, 177 | cardwidth = cardwidth, 178 | cardheight = cardheight, 179 | cols = cols, 180 | rows = rows, 181 | mainfont = mainfont, 182 | googlefonts = googlefonts, 183 | output = "pagedown::business_card", 184 | ... 185 | ) %>% 186 | purrr::discard(is_yml_blank) %>% 187 | as_yml() 188 | } 189 | 190 | #' @export 191 | #' @rdname pagedown_business_card_template 192 | pagedown_person <- function(...) { 193 | pagedown_business_card_template(...) %>% 194 | yml_discard("output") %>% 195 | unclass() 196 | } 197 | -------------------------------------------------------------------------------- /inst/addin/new_yaml/server.R: -------------------------------------------------------------------------------- 1 | # Server ------------------------------------------------------------------ 2 | library(shiny) 3 | library(miniUI) 4 | 5 | shiny::shinyServer(function(input, output, session){ 6 | shiny::observe({ 7 | if (input$export_file %in% c("YAML", "R Markdown")) { 8 | file_name <- ifelse(input$export_file == "YAML", "_output.yml", "Untitled.Rmd") 9 | shiny::updateTextInput(session, "file_path", value = file_name) 10 | } 11 | }) 12 | 13 | params_handlers <- shiny::reactiveValues( 14 | params = list(), 15 | value = list(), 16 | input = list(), 17 | label = list(), 18 | created = list() 19 | ) 20 | params_observers <- shiny::reactiveValues(observers = list()) 21 | 22 | shiny::observeEvent( 23 | input$add_param, { 24 | shiny::req(input$param) 25 | shiny::req(input$param_value) 26 | if (!is.null(params_handlers$params[[input$param]])) { 27 | shiny::removeUI(glue::glue("#param_{input$param}")) 28 | shiny::removeUI(glue::glue("#modal_param_{input$param}")) 29 | params_observers$observers[[input$param]]$destroy() 30 | for (x in names(params_handlers)) params_handlers[[x]][[input$param]] <- NULL 31 | } 32 | 33 | selector <- ifelse( 34 | purrr::is_empty(params_handlers$params), 35 | "holder", 36 | glue::glue("{params_handlers$params[[length(params_handlers$params)]]}") 37 | ) 38 | 39 | shiny::insertUI( 40 | selector = glue::glue("#param_{selector}"), 41 | where = "afterEnd", 42 | ui = ui_param( 43 | input$param, 44 | input$param_value, 45 | stringr::str_remove(input$shiny_fun, "shiny_"), 46 | input$param_label 47 | ) 48 | ) 49 | 50 | if (!is.null(input$shiny_fun) && input$shiny_fun != "") { 51 | shiny::insertUI( 52 | selector = "#modal_holder", 53 | where = "afterEnd", 54 | ui = output_modal( 55 | shiny_switch(input$shiny_fun), 56 | modal_name = glue::glue("param_{input$param}"), 57 | title = "Input options", 58 | id = glue::glue("modal_param_{input$param}"), 59 | ns = "shiny" 60 | ) 61 | ) 62 | } 63 | purrr::walk( 64 | c("param", "param_value", "param_label"), 65 | shiny::updateTextInput, 66 | value = "", 67 | session = session 68 | ) 69 | 70 | params_handlers$params[[input$param]] <- input$param 71 | params_handlers$value[[input$param]] <- input$param_value 72 | params_handlers$input[[input$param]] <- input$shiny_fun 73 | params_handlers$label[[input$param]] <- ifelse( 74 | input$param_label == "" | purrr::is_empty(input$param_label), 75 | input$param, input$param_label 76 | ) 77 | }) 78 | 79 | 80 | shiny::observeEvent(params_handlers$params, { 81 | for (i in seq_along(params_handlers$params)) { 82 | param <- params_handlers$params[[i]] 83 | rmv_button <- glue::glue("remove_param_{param}") 84 | if (is.null(params_handlers$created[[param]])) { 85 | params_observers$observers[[param]] <- shiny::observeEvent( 86 | input[[rmv_button]], { 87 | shiny::removeUI(glue::glue("#param_{param}")) 88 | params_handlers$created[[param]] <- NULL 89 | params_handlers$params[[param]] <- NULL 90 | }, 91 | ignoreInit = TRUE, 92 | once = TRUE 93 | ) 94 | 95 | params_handlers$created[[param]] <- TRUE 96 | } 97 | } 98 | 99 | }) 100 | 101 | shiny::observeEvent(input$done, { 102 | input_date <- swap_arg(as.character(input$date)) 103 | if (input$use_date) input_date <- NULL 104 | 105 | shiny_yml <- yml_empty() %>% 106 | yml_author(swap_arg(input$author)) %>% 107 | yml_date(input_date) %>% 108 | yml_title(swap_arg(input$title)) %>% 109 | yml_subtitle(swap_arg(input$subtitle)) %>% 110 | capture_output_functions(input) %>% 111 | capture_params(params_handlers, input) %>% 112 | yml_keywords(swap_arg(input$keywords)) %>% 113 | yml_subject(swap_arg(input$subject)) %>% 114 | yml_category(swap_arg(input$category)) %>% 115 | yml_abstract(swap_arg(input$abstract)) %>% 116 | yml_description(swap_arg(input$description)) %>% 117 | yml_lang(swap_arg(input$lang)) %>% 118 | yml_resource_files(swap_arg(input$resource_files$name)) %>% 119 | yml_clean(swap_arg(input$clean, .default = TRUE)) %>% 120 | pass_if( 121 | is_yml_blank(swap_arg(input$runtime)), 122 | yml_runtime, 123 | swap_arg(input$runtime) 124 | ) %>% 125 | yml_latex_opts( 126 | fontsize = swap_arg(input$fontsize), 127 | fontfamily = swap_arg(input$fontfamily), 128 | linkcolor = swap_arg(input$linkcolor), 129 | citecolor = swap_arg(input$citecolor), 130 | urlcolor = swap_arg(input$urlcolor), 131 | documentclass = swap_arg(input$documentclass), 132 | classoption = swap_arg(input$classoption), 133 | indent = swap_arg(input$indent, .default = FALSE), 134 | geometry = swap_arg(input$geometry), 135 | links_as_notes = swap_arg(input$links_as_notes, .default = FALSE), 136 | lof = swap_arg(input$lof, .default = FALSE), 137 | lot = swap_arg(input$lot, .default = FALSE), 138 | thanks = swap_arg(input$thanks), 139 | biblio_title = swap_arg(input$biblio_title), 140 | biblio_style = swap_arg(input$biblio_style), 141 | natbiboptions = swap_arg(input$natbiboptions), 142 | biblatexoptions = swap_arg(input$biblatexoptions) 143 | ) %>% 144 | yml_citations( 145 | bibliography = swap_arg(input$bibliography$name), 146 | csl = swap_arg(input$csl$name), 147 | link_citations = swap_arg(input$link_citations, .default = FALSE), 148 | suppress_bibliography = swap_arg(input$suppress_bibliography, .default = FALSE) 149 | ) %>% 150 | yml_discard(~is_yml_blank(.x)) 151 | 152 | export_f <- switch( 153 | input$export_file, 154 | "R Markdown" = use_rmarkdown, 155 | "YAML" = use_yml_file, 156 | "Place YAML on clipboard" = use_yml 157 | ) 158 | 159 | if (input$export_file == "R Markdown") { 160 | path <- input$file_path 161 | template <- input$rmd_template$name 162 | export_f <- purrr::partial(export_f, path = path, template = template) 163 | } 164 | 165 | if (input$export_file == "YAML") { 166 | path <- input$file_path 167 | export_f <- purrr::partial(export_f, path = path) 168 | } 169 | 170 | shiny::onStop(function() export_f(shiny_yml)) 171 | shiny::stopApp() 172 | }) 173 | }) 174 | -------------------------------------------------------------------------------- /vignettes/yaml-overview.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "YAML: an Overview" 3 | output: 4 | prettydoc::html_pretty: 5 | theme: tactile 6 | vignette: | 7 | %\VignetteIndexEntry{YAML: an Overview} 8 | %\VignetteEngine{knitr::rmarkdown} 9 | %\VignetteEncoding{UTF-8} 10 | --- 11 | 12 | ```{r, include = FALSE} 13 | knitr::opts_chunk$set( 14 | echo = FALSE, 15 | message = FALSE, 16 | collapse = TRUE, 17 | comment = "", 18 | warning = FALSE 19 | ) 20 | ``` 21 | 22 | ```{r setup} 23 | library(ymlthis) 24 | oldoption <- options(devtools.name = "Malcolm Barrett", crayon.enabled = FALSE) 25 | ``` 26 | 27 | ```{r pandoc_check, echo=FALSE} 28 | if (!rmarkdown::pandoc_available()) { 29 | cat("pandoc is required to use ymlthis. Please visit https://pandoc.org/ for more information.") 30 | knitr::knit_exit() 31 | } 32 | ``` 33 | 34 | # Basic syntax 35 | 36 | The basic syntax of YAML is to use key-value pairs in the format `key: value`. A YAML code block should be fenced in with `---` before and after (you can also use `...` to end the YAML block, but this is not very common in **R Markdown**). 37 | 38 | ```{r} 39 | yml(date = FALSE) %>% 40 | asis_yaml_output() 41 | ``` 42 | 43 | In R, the equivalent structure is a list with named character vector: `list(author = "Malcolm Barrett")`. In fact, you can call this list in **R Markdown** using the `metadata` object; in this case, `metadata$author` will return `"Malcolm Barrett"` 44 | 45 | In YAML, spaces are used to indicate nesting. When we want to specify the output function `pdf_document(toc = TRUE)`, we need to nest it under the `output` field. We also need to nest `toc` under `pdf_document` so that it gets passed to that function correctly. 46 | 47 | ```{r, warning = FALSE} 48 | yml_empty() %>% 49 | yml_output(pdf_document(toc = TRUE)) %>% 50 | asis_yaml_output() 51 | ``` 52 | 53 | In R, the equivalent structure is a nested list, each with a name: `list(output = list(pdf_document = list(toc = TRUE)))`. Similarly, you can call this in R Markdown using the `metadata` object, e.g. `metadata$output$pdf_document$toc`. The hierarchical structure (which you can see with `draw_yml_tree()`) looks like this: 54 | 55 | ```{r, warning = FALSE} 56 | yml_empty() %>% 57 | yml_output(pdf_document(toc = TRUE)) %>% 58 | draw_yml_tree() 59 | ``` 60 | 61 | Without the extra indents, YAML doesn't know `toc` is connected to `pdf_document` and thinks the value of `pdf_document` is `NULL`. YAML that looks like this: 62 | 63 | ```yaml 64 | --- 65 | output: 66 | pdf_document: 67 | toc: true 68 | --- 69 | ``` 70 | has a hierarchy that looks like this: 71 | 72 | ```{r} 73 | list(output = list(pdf_document = NULL), toc = TRUE) %>% 74 | as_yml() %>% 75 | draw_yml_tree() 76 | ``` 77 | 78 | If you use output functions without additional arguments, the value of `output` can simply be the name of the function. 79 | 80 | ```{r} 81 | yml_empty() %>% 82 | yml_output(html_document()) %>% 83 | asis_yaml_output() 84 | ``` 85 | 86 | However, if you're specifying more than one output type, you must use the nesting syntax. If you don't want to include additional arguments, use `"default"` as the function's value. 87 | 88 | ```{r, warning = FALSE} 89 | yml_empty() %>% 90 | yml_output(html_document(), pdf_document(toc = TRUE)) %>% 91 | asis_yaml_output() 92 | ``` 93 | 94 | Some YAML fields take unnamed vectors as their value. You can specify an element of the vector by adding a new line and `-` (note that the values are not indented below `category` here). 95 | 96 | ```{r} 97 | yml_empty() %>% 98 | yml_category(c("R", "Reprodicible Research")) %>% 99 | asis_yaml_output() 100 | ``` 101 | 102 | In R, the equivalent structure is a list with a named vector: `list(categories = c("R", "Reprodicible Research"))`. `metadata$category` will return `c("R", "Reprodicible Research")`. Another way to specify vectors is to use `[]` with each object separated by a column, as in the syntax for `c()`. This YAML is equivalent to the YAML above: 103 | 104 | ```yaml 105 | --- 106 | category: [R, Reprodicible Research] 107 | --- 108 | ``` 109 | 110 | By default, **ymlthis** uses the `-` syntax for vectors.`-` is also used to group elements together. For instance, in the `params` field for parameterized reports, we group parameter information together by using `-`. The first line is the name and value of the parameter, while all the lines until the next `-` are extra information about the parameter. While you can use `metadata` to call objects in `params`, `params` has it's own object you can call directly: `params$a` and `params$data` will return the values of `a` and `data`. 111 | 112 | ```{r} 113 | yml_empty() %>% 114 | yml_params( 115 | list(a = 1, input = "numeric"), 116 | list(data = "data.csv", input = "text") 117 | ) %>% 118 | asis_yaml_output() 119 | ``` 120 | 121 | In R, the equivalent structure is a nested list that contains a list of unnamed lists: `list(param = list(list(a = 1, input = numeric), list(data = "data.csv", input = "file")))`. The inner-most lists group items together, e.g. `list(a = 1, input = numeric)` groups `a` and `input`. 122 | 123 | ```{r} 124 | yml_empty() %>% 125 | yml_params( 126 | list(a = 1, input = "numeric"), 127 | list(data = "data.csv", input = "text") 128 | ) %>% 129 | draw_yml_tree() 130 | ``` 131 | 132 | # Types in YAML 133 | 134 | You may have noticed that strings in YAML don't always need to be quoted. However, it can be useful to explicitly wrap strings in quotes when they contain special characters like `:` and `@`. 135 | 136 | ```{r} 137 | yml_empty() %>% 138 | yml_title("R Markdown: An Introduction") %>% 139 | asis_yaml_output() 140 | ``` 141 | 142 | R code can be written as inline expressions `` `r knitr::inline_expr('expr')` ``. `yml_code()` will capture R code for you and put it in a valid format. R code in `params` needs to be slightly different: use `!r` (e.g. `!r expr`) to call an R object. 143 | 144 | ```yaml 145 | author: '`r knitr::inline_expr('whoami::fullname()')`' 146 | params: 147 | date: !r Sys.Date() 148 | ``` 149 | 150 | Logical values in YAML are unusual: `true/false`, `yes/no`, and `on/off` are all equivalent to `TRUE/FALSE` in R. Any of these turn on the table of contents: 151 | 152 | ```yaml 153 | toc: true 154 | toc: yes 155 | toc: on 156 | ``` 157 | 158 | By default, **ymlthis** uses `true/false`. If you want to use any of these values literally (e.g. you want a string equal to `"yes"`), you need to wrap them in quotation marks: 159 | 160 | ```{r} 161 | yml_empty() %>% 162 | yml_params(x = "yes") %>% 163 | asis_yaml_output() 164 | ``` 165 | 166 | `NULL` can be specified using `null` or `~`. By default, **ymlthis** uses `null`. If you want to specify an empty vector, use `[]`, e.g. `category: []`. For an empty string, just use empty quotation marks (`""`). 167 | 168 | # Sources of YAML 169 | 170 | Where do the YAML fields you use in **R Markdown** come from? Many YAML fields that we use come from Pandoc from the **rmarkdown** package. These both use YAML to specify the build of the document and to pass information to be printed in a template. Pandoc templates can also be customized to add new YAML. The most common sources of YAML are: 171 | 172 | 1. Pandoc 173 | 1. **R Markdown** 174 | 1. Output functions (such as `rmarkdown::pdf_document()`) 175 | 1. Custom Pandoc templates 176 | 1. **R Markdown** extension packages (such as **blogdown**) 177 | 1. Hugo (in the case of **blogdown**) 178 | 179 | Because YAML is an extensible approach to metadata, and there is often no way to validate that your YAML is correct. YAML will often fail silently if you, for instance, make a typo in the field name or misspecify the nesting between fields. For more information on the fields available in R Markdown and friends, see the [YAML Fieldguide](yaml-fieldguide.html). 180 | 181 | 182 | ```{r, include=FALSE} 183 | options(oldoption) 184 | ``` 185 | -------------------------------------------------------------------------------- /inst/addin/new_yaml/global.R: -------------------------------------------------------------------------------- 1 | # Resources --------------------------------------------------------------- 2 | library(ymlthis) 3 | shiny::addResourcePath("sbs", system.file("www", package = "shinyBS")) 4 | 5 | # Functions --------------------------------------------------------------- 6 | author_name <- function() { 7 | tryCatch( 8 | ymlthis:::get_author_name(), 9 | error = function(e) "" 10 | ) 11 | } 12 | 13 | args_as_char <- function(x) { 14 | if (is.null(x)) return("NULL") 15 | if (is.call(x)) return(rlang::quo_text(x)) 16 | as.character(x) 17 | } 18 | 19 | arg_textInput <- function(arg_name, arg_val, f_name, id = NULL) { 20 | if (is.null(id)) id <- f_name 21 | input_id <- glue::glue("{id}_{arg_name}") 22 | ph <- args_as_char(arg_val) 23 | arg_name <- glue::glue("{arg_name}") 24 | shiny::textInput(input_id, shiny::HTML(arg_name), placeholder = ph) 25 | } 26 | 27 | ui_function_args <- function(f_name, id = NULL, ns = "rmarkdown") { 28 | args <- rlang::fn_fmls(utils::getFromNamespace(f_name, ns)) 29 | if (ns == "shiny") args[c("inputId", "label", "value")] <- NULL 30 | tags <- purrr::map2( 31 | names(args), 32 | args, 33 | arg_textInput, 34 | f_name = f_name, 35 | id = id 36 | ) 37 | shiny::tagList(tags) 38 | } 39 | 40 | output_buttons <- function(f_name, short_name) { 41 | if (is.na(f_name)) return(NULL) 42 | id <- glue::glue("button_{f_name}") 43 | txt <- glue::glue("Set {short_name} options") 44 | shiny::conditionalPanel( 45 | condition = glue::glue("input.output_function.includes('{f_name}')"), 46 | shiny::actionButton(id, txt, style = "margin-top:4px; margin-right:2px"), 47 | style = "display:inline-block" 48 | ) 49 | } 50 | 51 | output_modal <- function(f_name, modal_name = NULL, title = "Output options", id = NULL, ns = "rmarkdown") { 52 | if (is.null(modal_name)) modal_name <- f_name 53 | shinyBS::bsModal( 54 | glue::glue("modal_{modal_name}"), 55 | glue::glue("{title}: {f_name}"), 56 | glue::glue("button_{modal_name}"), 57 | ui_function_args(f_name, id = id, ns = ns), 58 | size = "small" 59 | ) 60 | } 61 | 62 | ui_output_action_buttons <- function(x) { 63 | tags <- purrr::map2(x, names(x), output_buttons) 64 | shiny::tagList(tags) 65 | } 66 | 67 | ui_output_modals <- function(x) { 68 | tags <- purrr::map(x, output_modal) 69 | shiny::tagList(tags) 70 | } 71 | 72 | param_label <- function(label, x) { 73 | if (x == "" || is.null(x)) return(NULL) 74 | p_html <- "{x}" 75 | shiny::div(shiny::HTML(glue::glue(p_html))) 76 | } 77 | 78 | ui_param <- function(param, value, shiny_function, label) { 79 | input_button <- shiny::actionButton( 80 | glue::glue("button_param_{param}"), 81 | glue::glue("options") 82 | ) 83 | if ((shiny_function == "" || is.null(shiny_function))) input_button <- NULL 84 | param_row <- shiny::fillRow( 85 | param_label("param", param), 86 | param_label("value", value), 87 | param_label("label", label), 88 | input_button, 89 | shinyBS::bsButton(glue::glue("remove_param_{param}"), "Remove", style = "danger"), 90 | height = 70 91 | ) 92 | shiny::tags$div(param_row, id = glue::glue("param_{param}")) 93 | } 94 | 95 | rmarkdown_outputs <- c( 96 | "html" = "html_document", 97 | "pdf" = "pdf_document", 98 | "word" = "word_document", 99 | "odt" = "odt_document", 100 | "rtf" = "rtf_document", 101 | "md" = "md_document", 102 | "ioslides" = "ioslides_presentation", 103 | "slidy" = "slidy_presentation", 104 | "beamer" = "beamer_presentation", 105 | "powerpoint" = "powerpoint_presentation" 106 | ) 107 | 108 | shiny_functions <- c( 109 | "", 110 | "checkbox" = "shiny_checkbox", 111 | "date" = "shiny_date", 112 | "file" = "shiny_file", 113 | "numeric" = "shiny_numeric", 114 | "password" = "shiny_password", 115 | "radio" = "shiny_radio", 116 | "select" = "shiny_select", 117 | "slider" = "shiny_slider", 118 | "text" = "shiny_text" 119 | ) 120 | 121 | shiny_switch <- function(x) { 122 | switch( 123 | x, 124 | "shiny_checkbox" = "checkboxInput", 125 | "shiny_numeric" = "numericInput", 126 | "shiny_slider" = "sliderInput", 127 | "shiny_date" = "dateInput", 128 | "shiny_text" = "textInput", 129 | "shiny_file" = "fileInput", 130 | "shiny_radio" = "radioButtons", 131 | "shiny_select" = "selectInput", 132 | "shiny_password" = "passwordInput" 133 | ) 134 | } 135 | 136 | swap_arg <- function(x, .default = NULL) { 137 | if (purrr::is_empty(x) || x == "") return(yml_blank()) 138 | if (identical(.default, x)) return(yml_blank()) 139 | x 140 | } 141 | 142 | pass_if <- function(x, pred, .f, ...) { 143 | if (pred) return(x) 144 | .f(x, ...) 145 | } 146 | 147 | input_starts_with <- function(input, .match) { 148 | matches <- names(input)[startsWith(names(input), .match)] 149 | matched_inputs <- purrr::map(matches, ~input[[.x]]) 150 | names(matched_inputs) <- matches 151 | matched_inputs 152 | } 153 | 154 | capture_arg <- function(x) { 155 | if (x == "" || stringr::str_detect(x, "[\"\']{2}")) return(x) 156 | arg_guess <- type.convert(x, as.is = TRUE) 157 | if (is.character(arg_guess)) arg_guess <- glue::glue("\"{arg_guess}\"") 158 | 159 | arg_guess 160 | } 161 | 162 | parse_arguments <- function(x) { 163 | if (purrr::is_empty(x) || x == "") return("") 164 | args <- purrr::map2_chr(x, names(x), ~glue::glue("{.y} = {capture_arg(.x)}")) 165 | glue::glue_collapse(args, ", ") 166 | } 167 | parse_dots <- function(fn_args) { 168 | dot_col <- stringr::str_detect(names(fn_args), "\\.\\.\\.") 169 | if (!any(dot_col)) return(fn_args) 170 | dot_txt <- fn_args[[which(dot_col)]] 171 | dot_list <- glue::glue("list({dot_txt})") %>% 172 | rlang::parse_expr() %>% 173 | rlang::eval_tidy() 174 | x <- fn_args[!dot_col] 175 | x[names(dot_list)] <- dot_list 176 | x 177 | } 178 | 179 | parse_output <- function(input, .f, .match = NULL, value = NULL, label = NULL) { 180 | if (is.null(.match)) .match <- .f 181 | fn_args <- input_starts_with(input, .match) %>% 182 | purrr::map(swap_arg) %>% 183 | purrr::discard(is_yml_blank) %>% 184 | parse_dots() 185 | fn_args <- fn_args[names(fn_args) != .match] 186 | names(fn_args) <- stringr::str_remove_all(names(fn_args), glue::glue("{.match}_?")) 187 | if (.f %in% shiny_functions) { 188 | fn_args <- c(value = value, label = label, fn_args) 189 | } 190 | .call <- glue::glue("{.f}({parse_arguments(fn_args)})") 191 | .call 192 | } 193 | 194 | capture_output_functions <- function(.yml, input) { 195 | .fs <- input$output_function 196 | if (purrr::is_empty(.fs) || .fs == "") return(.yml) 197 | fn_calls <- purrr::map_chr(.fs, parse_output, input = input) %>% 198 | glue::glue_collapse(sep = ", ") 199 | glue::glue(".yml %>% yml_output({fn_calls})") %>% 200 | rlang::parse_expr() %>% 201 | rlang::eval_tidy() 202 | } 203 | 204 | parse_param <- function(param, value, shiny_input, input, label) { 205 | if (is_yml_blank(swap_arg(shiny_input))) { 206 | return(glue::glue("\"{param}\" = {capture_arg(value)}")) 207 | } 208 | .match <- glue::glue("modal_param_{param}") 209 | shiny_call <- parse_output( 210 | input, 211 | shiny_input, 212 | .match = .match, 213 | value = value, 214 | label = label 215 | ) 216 | glue::glue("\"{param}\" = {shiny_call}") 217 | } 218 | 219 | capture_params <- function(.yml, params_handlers, input) { 220 | if (purrr::is_empty(params_handlers$params)) { 221 | return(.yml) 222 | } 223 | index <- c("params", "value", "input", "label") 224 | rv_list <- shiny::reactiveValuesToList(params_handlers)[index] 225 | names(rv_list) <- c("param", "value", "shiny_input", "label") 226 | param_list <- purrr::pmap_chr( 227 | rv_list, 228 | parse_param, 229 | input = input 230 | ) %>% 231 | glue::glue_collapse(sep = ", ") 232 | glue::glue(".yml %>% yml_params({param_list})") %>% 233 | rlang::parse_expr() %>% 234 | rlang::eval_tidy() 235 | } 236 | --------------------------------------------------------------------------------