Set Top-level YAML options for bookdown

bookdown uses YAML in three main places, as described in the bookdown book: index.Rmd, _output.yml, and _bookdown.yml. index.Rmd can take most YAML. _output.yml is intended for output-related YAML, such as that produced by yml() %>% yml_output(bookdown::pdf_book()). _bookdown.yml is intended for configuring the build of the book. Pass the results of the yml_*() functions to use_index_rmd(), use_bookdown_yml(), use_output_yml() to write them to these files. yml_bookdown_site() adds the site: "bookdown::bookdown_site" to the YAML metadata.

yml_bookdown_opts(
  .yml,
  book_filename = yml_blank(),
  delete_merged_file = yml_blank(),
  before_chapter_script = yml_blank(),
  after_chapter_script = yml_blank(),
  edit = yml_blank(),
  history = yml_blank(),
  rmd_files = yml_blank(),
  rmd_subdir = yml_blank(),
  output_dir = yml_blank(),
  clean = yml_blank(),
  ...
)

yml_bookdown_site(.yml)

Arguments

.yml

a yml object created by yml(), as_yml(), or returned by a yml_*() function

book_filename

A character vector, the filename of the main .Rmd file, the .Rmd file that is created by merging all chapters. By default, it is called "_main.Rmd".

delete_merged_file

Logical. Delete the main .Rmd file if it exists?

before_chapter_script, after_chapter_script

A character vector of one or more R scripts to be executed before or after each chapter

edit

A URL that collaborators can click to edit the .Rmd source document of the current page, usually a link to a GitHub repository. This link should have %s where the actual .Rmd filename for each page will go.

history

Similar to edit, a link to the edit/commit history of the current page.

rmd_files

A character vector, the order order of .Rmd files for the book. rmd_files can also be a named list where each element of the list is named for the output type, e.g. "html" or "latex". By default, bookdown merges all .Rmd files by the order of filenames.

rmd_subdir

whether to search for book source .Rmd files in subdirectories (by default, only the root directory is searched). This may be either a boolean (e.g. TRUE will search for book source .Rmd files in the project directory and all subdirectories) or vector of paths if you want to search for book source .Rmd files in a subset of subdirectories.

output_dir

the output directory of the book ("_book" by default)

clean

a character vector of files and directories to be cleaned by the bookdown::clean_book() function.

...

additional named R objects, such as characters or lists, to transform into YAML

Value

a yml object

See also

use_index_rmd() use_bookdown_yml() use_output_yml()

Other yml: asis_yaml_output(), bib2yml(), draw_yml_tree(), has_field(), read_json(), use_yml_defaults(), use_yml_file(), use_yml(), yml_author(), yml_blogdown_opts(), yml_citations(), yml_clean(), yml_distill_opts(), yml_latex_opts(), yml_output(), yml_pagedown_opts(), yml_params(), yml_pkgdown(), yml_reference(), yml_replace(), yml_resource_files(), yml_rsconnect_email(), yml_rticles_opts(), yml_runtime(), yml_site_opts(), yml_toc(), yml_vignette()

Other bookdown: gitbook_config()

Examples

yml_empty() %>%
  yml_bookdown_opts(
    book_filename = "my-book.Rmd",
    before_chapter_script = c("script1.R", "script2.R"),
    after_chapter_script = "script3.R",
    edit = "https =//github.com/rstudio/bookdown-demo/edit/master/%s",
    output_dir = "book-output",
    clean = c("my-book.bbl", "R-packages.bib")
 )
#> ---
#> book_filename: my-book.Rmd
#> before_chapter_script:
#> - script1.R
#> - script2.R
#> after_chapter_script: script3.R
#> edit: https =//github.com/rstudio/bookdown-demo/edit/master/%s
#> output_dir: book-output
#> clean:
#> - my-book.bbl
#> - R-packages.bib
#> ---
#> 

yml_empty() %>%
  yml_bookdown_opts(
    rmd_files = list(
      html = c("index.Rmd", "abstract.Rmd", "intro.Rmd"),
      latex = c("abstract.Rmd", "intro.Rmd")
    )
 )
#> ---
#> rmd_files:
#>   html:
#>   - index.Rmd
#>   - abstract.Rmd
#>   - intro.Rmd
#>   latex:
#>   - abstract.Rmd
#>   - intro.Rmd
#> ---
#> 

 x <- yml_empty() %>%
  yml_title("A Minimal Book Example") %>%
  yml_date(yml_code(Sys.Date())) %>%
  yml_author("Yihui Xie") %>%
  yml_bookdown_site() %>%
  yml_latex_opts(
    documentclass = "book",
    bibliography = c("book.bib", "packages.bib"),
    biblio_style = "apalike"
  ) %>%
  yml_citations(
    link_citations = TRUE
  ) %>%
  yml_description("This is a minimal example of using
  the bookdown package to write a book.")

x
#> ---
#> title: A Minimal Book Example
#> date: '`r Sys.Date() `'
#> author: Yihui Xie
#> site: bookdown::bookdown_site
#> documentclass: book
#> biblio-style: apalike
#> bibliography:
#> - book.bib
#> - packages.bib
#> link-citations: true
#> description: |-
#>   This is a minimal example of using
#>     the bookdown package to write a book.
#> ---
#> 


# \donttest{
output_yml <- yml_empty() %>%
  yml_output(
    bookdown::gitbook(
      lib_dir = "assets",
      split_by = "section",
      config = gitbook_config(toolbar_position = "static")
    ),
    bookdown::pdf_book(keep_tex = TRUE),
    bookdown::html_book(css = "toc.css")
  )
output_yml
#> ---
#> output:
#>   bookdown::gitbook:
#>     lib_dir: assets
#>     split_by: section
#>     config:
#>       toolbar:
#>         position: static
#>   bookdown::pdf_book:
#>     keep_tex: true
#>   bookdown::html_book:
#>     css: toc.css
#> ---
#> 
# }