The YAML Fieldguide


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.

Basic YAML

Basic YAML
Help Page Argument Description
yml_runtime runtime The runtime target for rendering. static, the default, renders static documents; shiny allows you to include use Shiny in your document. shiny_prerendered is a subset of the shiny runtime that allows pre-rendering of app components (see the R Markdown site for more)
yml_clean clean Logical. Remove intermediate files that are created while making the R Markdown document?
yml_toc toc Logical. Use a Table of Contents?
yml_toc toc_depth An integer. The depth of headers to use in the TOC. Note that the actual YAML field is toc-depth.
yml_toc toc_title The title of the TOC. Note that the actual YAML field is toc-title.
yml_author name A character vector, name of the author(s)
yml_author affiliation The author’s affiliation; must match length of name, e.g. if name has length of two, affiliation must as well; use NA if you don’t want to include an affiliation for a given author.Note that not all formats support the affiliation field.
yml_author email The author email address. Note that not all formats support the email field.
yml_author date The date; by default this is “`r format(Sys.Date())`”, which will populate the date automatically.
yml_author format When the default date is used, the format passed to [format.Date()].
yml_author title A character vector, the title of the document
yml_author subtitle A character vector, the subtitle of the document. Not all R Markdown formats use subtitles, so it may depend on what you use in the output field (see [yml_output()]). It is available in pdf_document(), html_document(), and word_document() by default.
yml_author abstract A character vector, the abstract. Long character vectors are automatically wrapped using valid YAML syntax. This field is not available in all output formats; it is available in pdf_document() and html_document() by default.
yml_author keywords A character vector of keywords. This field is not available in all output formats; it is available in pdf_document(), html_document(), word_document(), odt_document(), and powerpoint_presentation() by default.
yml_author subject A character vector, the subject of the document. This field is not available in all output formats; it is available in pdf_document(), html_document(), word_document(), odt_document(), and powerpoint_presentation() by default.
yml_author description A character vector, a description of the document. This field is not available in all output formats; it is available in word_document(), odt_document(), and powerpoint_presentation() by default.
yml_author category A character vector, the category of the document. This field is not available in all output formats; it is available in word_document() and powerpoint_presentation() by default.
yml_author lang The document language using IETF language tags such as “en” or “en-US”. The Language subtag lookup tool can help find the appropriate tag.

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.

LaTeX/PDF Options

LaTeX/PDF Options
Help Page Argument Description
yml_latex_opts block_headings make paragraph and subparagraph (fourth- and fifth-level headings, or fifth- and sixth-level with book classes) free-standing rather than run-in; requires further formatting to distinguish from subsubsection (third- or fourth-level headings). Note that the YAML field is actually called block-headings.
yml_latex_opts classoption a character vector of options for document class, e.g. “oneside”
yml_latex_opts documentclass the document class usually “article”, “book”, or “report”
yml_latex_opts geometry a character vector of options for the geometry LaTeX package, e.g. “margin=1in”
yml_latex_opts indent Logical. Use document class settings for indentation? The default LaTeX template otherwise removes indentation and adds space between paragraphs.
yml_latex_opts linestretch adjusts line spacing using the setspace LaTeX package, e.g. 1.25, 1.5
yml_latex_opts margin_left, margin_right, margin_top, margin_bottom sets margins if geometry is not used, otherwise geometry overrides these. Note that the actual YAML fields use - instead of _, e.g. margin-left.
yml_latex_opts pagestyle control the pagestyle LaTeX command: the default article class supports “plain” (default), “empty” (no running heads or page numbers), and “headings” (section titles in running heads)
yml_latex_opts papersize paper size, e.g. letter, a4
yml_latex_opts secnumdepth numbering depth for sections (with --number-sections pandoc)
yml_latex_opts fontenc allows font encoding to be specified through fontenc LaTeX package (with pdflatex); default is “T1” (see LaTeX font encodings guide)
yml_latex_opts fontfamily font package for use with pdflatex: TeX Live includes many options, documented in the LaTeX Font Catalogue. The default is “Latin Modern”.
yml_latex_opts fontfamilyoptions a character vector of options for fontfamily.
yml_latex_opts fontsize font size for body text. The standard classes allow “10pt”, “11pt”, and “12pt”.
yml_latex_opts mainfont, sansfont, monofont, mathfont, CJKmainfont font families for use with xelatex or lualatex: take the name of any system font, using the fontspec LaTeX package. CJKmainfont uses the xecjk LaTeX package..
yml_latex_opts mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions, CJKoptions a character vector of options to use with mainfont, sansfont, monofont, mathfont, CJKmainfont in xelatex and lualatex. Allow for any choices available through fontspec.
yml_latex_opts microtypeoptions a character vector of options to pass to the microtype LaTeX package.
yml_latex_opts colorlinks Logical. Add color to link text? Automatically enabled if any of linkcolor, filecolor, citecolor, urlcolor, or toccolor are set.
yml_latex_opts linkcolor, filecolor, citecolor, urlcolor, toccolor color for internal links, external links, citation links, linked URLs, and links in table of contents, respectively: uses options allowed by xcolor, including the dvipsnames, svgnames, and x11names lists
yml_latex_opts links_as_notes Logical. Print links as footnotes? Note that the actual YAML field is links-as-notes
yml_latex_opts lof, lot Logical. Include list of figures or list of tables?
yml_latex_opts thanks contents of acknowledgments footnote after document title
yml_latex_opts toc include table of contents
yml_latex_opts toc_depth level of section to include in table of contents. Note that the actual YAML field is toc-depth
yml_latex_opts biblatexoptions list of options for biblatex.
yml_latex_opts biblio_style bibliography style, when used with natbib and biblatex. Note that the actual YAML field is biblio-style
yml_latex_opts biblio_title bibliography title, when used with natbib and biblatex. Note that the actual YAML field is biblio-title
yml_latex_opts bibliography a path to the bibliography file to use for references
yml_latex_opts natbiboptions a character vector of options for natbib

R Markdown Websites

R Markdown Websites
Help Page Argument Description
yml_vignette title The title of the vignette
yml_vignette engine The rendering engine for the vignette (“knitr::rmarkdown” by default)
yml_vignette encoding The character encoding for the document (“UTF-8” by default).
yml_site_opts name The name of the website
yml_site_opts favicon Path to a file to use as the favicon
yml_site_opts output_dir Directory to copy site content into ("_site" is the default if none is specified)
yml_site_opts include, exclude Files to include or exclude from the copied into output_dir. You can use * to indicate a wildcard selection, e.g. "*.csv".
yml_site_opts new_session Logical. Should each website file be rendered in a new R session?
yml_site_opts title The title of the website
yml_site_opts type The color scheme for the navigation bar: either “default” or “inverse”.
yml_site_opts left, right the side of the navbar a navbar_page() should go (see example)
yml_site_opts text The link text
yml_site_opts href The link URL
yml_site_opts icon An icon to include
yml_site_opts menu drop-down menus specified by including another navbar_page()

Citations

Citations
Help Page Argument Description
yml_citations bibliography a path to a bibliography file, such as a .bib file
yml_citations csl a path to a Citation Style Language (CSL) file. CSL files are used to specify the citation style; see the CSL repository for the CSL files of dozens of journals.
yml_citations citation_abbreviations Path to a CSL abbreviations JSON file. See the pandoc-citeproc documentation. Note that the actual YAML field is citation-abbreviations.
yml_citations link_citations Logical. Add citations hyperlinks to the corresponding bibliography entries? Note that the actual YAML field is link-citations.
yml_citations nocite Citation IDs ("@item1") to include in the bibliography even if they are not cited in the document. Including the wildcard pattern "@*" will include all citations in the bibliography regardless of if they’re cited in the document.
yml_citations suppress_bibliography Logical. Suppress bibliography?

blogdown YAML

blogdown YAML
Help Page Argument Description
yml_blogdown_opts draft Logical. Set post as a draft? Draft posts will not be rendered if the site is built via blogdown::build_site() or blogdown::hugo_build() but will be rendered in the local preview mode. See Section D.3 of the blogdown book.
yml_blogdown_opts publishdate A future date to publish the post. Future posts are only rendered in the local preview mode
yml_blogdown_opts weight This field can take a numeric value to tell Hugo the order of pages when sorting them, e.g., when you generate a list of all pages under a directory, and two posts have the same date, you may assign different weights to them to get your desired order on the list
yml_blogdown_opts slug A character string used as the tail of the post URL. It is particularly useful when you define custom rules for permanent URLs. See Section 2.2.2 of the blogdown book.
yml_blogdown_opts aliases A character vector of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure
yml_blogdown_opts audio A character vector of paths to audio files related to the page
yml_blogdown_opts date The date assigned to this page. This is usually fetched from the date field in front matter, but this behavior is configurable.
yml_blogdown_opts description The description for the content
yml_blogdown_opts expiration_date the date at which the content should no longer be published by Hugo. Note that the actual YAML field is expiryDate
yml_blogdown_opts headless if TRUE, sets a leaf bundle to be headless.
yml_blogdown_opts images A character vector of paths to images related to the page
yml_blogdown_opts keywords A character vector of the keywords for the content.
yml_blogdown_opts layout The layout Hugo should use while rendering the content. By default, layout matches type and is thus based on the directory. However, it’s possible to use additional layouts within a type. See Hugo’s Defining a Content Type documentation.
yml_blogdown_opts lastmod The date the content was last modified at
yml_blogdown_opts link_title used for creating links to content. Note that the actual YAML field is linkTitle
yml_blogdown_opts resources A named list. Used for configuring page bundle resources. See Hugo’s Page Resources documentation
yml_blogdown_opts series A character vector of series this page belongs to
yml_blogdown_opts summary A summary of the content in the .Summary Hugo page variable; see the content-summaries section of Hugo’s documentation.
yml_blogdown_opts title The title for the content
yml_blogdown_opts type The type of the content, which is based on the from the directory of the content if not specified
yml_blogdown_opts url The full path to the content from the web root
yml_blogdown_opts videos A character vector of paths to videos related to the page

bookdown YAML

bookdown YAML
Help Page Argument Description
yml_bookdown_opts 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".
yml_bookdown_opts delete_merged_file Logical. Delete the main .Rmd file if it exists?
yml_bookdown_opts before_chapter_script, after_chapter_script A character vector of one or more R scripts to be executed before or after each chapter
yml_bookdown_opts 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.
yml_bookdown_opts history Similar to edit, a link to the edit/commit history of the current page.
yml_bookdown_opts 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.
yml_bookdown_opts 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.
yml_bookdown_opts output_dir the output directory of the book ("_book" by default)
yml_bookdown_opts clean a character vector of files and directories to be cleaned by the bookdown::clean_book() function.

pkgdown YAML

pkgdown YAML
Help Page Argument Description
yml_pkgdown as_is Logical. Use the output_format and options that you have specified?
yml_pkgdown extension The output extension, e.g. “pdf”.
yml_pkgdown site_title The title of the website (by default, this is the package name). Note that the actual YAML is title (specified as site_title to avoid duplication with content titles).
yml_pkgdown destination The path where the site should be rendered (“docs/” by default)
yml_pkgdown url URL where the site will be published; setting the URL will allow other pkgdown sites to link to your site when needed, generate a sitemap.xml to increase the searchability of your site, and generate a CNAME.
yml_pkgdown toc_depth The depth of the headers included in the Table of Contents. Note that the actual YAML is depth and is nested under toc.
yml_pkgdown mode The development mode of the site, one of: “auto”, “release”, “development”, or “unreleased”. development controls where the site is built; the color of the package version; the optional tooltip associated with the version; and the indexing of the site by search engines. See ?pkgdown::build_site() for more details.
yml_pkgdown dev_destination The subdirectory used for the development site, which defaults to “dev/”. Note that the actual YAML is destination and is nested under development.
yml_pkgdown version_label Label to display for “development” and “unreleased” mode. One of: “danger” (the default), “default”, “info”, or “warning”.
yml_pkgdown version_tooltip A custom message to include in the version tooltip
yml_pkgdown bootswatch A bootswatch theme for the site. See the options at https://rstudio.github.io/shinythemes/.
yml_pkgdown ganalytics A Google Analytics tracking id
yml_pkgdown noindex Logical. Suppress indexing of your pages by web robots?
yml_pkgdown package an R package with with directories inst/pkgdown/assets and inst/pkgdown/templates to override the default templates and add additional assets; alternatively, you can specify this in path and assets
yml_pkgdown path A path to templates with which to override the default pkgdown templates
yml_pkgdown assets A path to additional assets to include
yml_pkgdown default_assets Logical. Include default assets?
yml_pkgdown title The title of the article, reference, tutorial, or other resource
yml_pkgdown desc A description of the article or reference
yml_pkgdown contents The contents, which can also be dplyr-style tidy selectors (e.g "contains('index')").
yml_pkgdown exclude What to exclude of the what’s captured by contents
yml_pkgdown one_page Logical. Create one page per release for NEWS.md?
yml_pkgdown name The name of the file
yml_pkgdown tutorial_url The tutorial URL to embed in an iframe
yml_pkgdown source A URL to the source code of the tutorial
yml_pkgdown dev The graphics device (default: “grDevices::png”)
yml_pkgdown dpi The DPI (default: 96)
yml_pkgdown dev.args A vector of arguments to pass to dev
yml_pkgdown fig.ext The figure extension (default: “png”)
yml_pkgdown fig.width The figure width (default: 7.2916667)
yml_pkgdown fig.height The figure height (default: NULL)
yml_pkgdown fig.retina The figure retina value (default: 2)
yml_pkgdown fig.asp The aspect ratio (default: 1.618)
yml_pkgdown api_key The API key provided by docsearch (see the pkgdown vignette)
yml_pkgdown index_name The index name provided by docsearch (see the pkgdown vignette)
yml_pkgdown doc_url the URL specifying the location of your documentation. Note that the actual YAML field is url but is nested.

pagedown YAML

pagedown YAML
Help Page Argument Description
yml_pagedown_opts toc Logical. Use a table of contents?
yml_pagedown_opts toc_title The title for the table of contents. Note that the actual YAML field is toc-title
yml_pagedown_opts lot Logical. Use a list of figures?
yml_pagedown_opts lot_title The title for the list of figures. Note that the actual YAML field is lot-title
yml_pagedown_opts chapter_name The chapter title prefix
yml_pagedown_opts links_to_footnotes Logical. Transform all the URLs to footnotes? Note that the actual YAML field is links-to-footnotes
yml_pagedown_opts paged_footnotes Logical. Render notes as footnotes? Note that the actual YAML field is paged-footnotes
pagedown_business_card_template name The name
pagedown_business_card_template person When you are creating business cards for numerous people with shared information, passing values to the person field can override the default values, which can be any of the values accepted by this function. Use pagedown_person() to do so or manually provide them using list(field = value).
pagedown_business_card_template title The title of the person
pagedown_business_card_template phone A phone number
pagedown_business_card_template email An email address
pagedown_business_card_template url A website URL
pagedown_business_card_template address The address
pagedown_business_card_template logo A path to a logo file
pagedown_business_card_template .repeat The number of cards to repeat. Note that the actual YAML field is repeat.
pagedown_business_card_template paperwidth The paper width
pagedown_business_card_template paperheight The paper height
pagedown_business_card_template cardwidth The width of the card
pagedown_business_card_template cardheight The height of the card
pagedown_business_card_template cols The number of columns in the card grid
pagedown_business_card_template rows The rows of columns in the card grid
pagedown_business_card_template mainfont The font
pagedown_business_card_template googlefonts A character vector of Google Fonts

distill YAML

distill YAML
Help Page Argument Description
yml_distill_opts draft Logical. Set the post to be a draft? Draft posts won’t be published.
yml_distill_opts slug The abbreviated version of the citation included in the BibTeX entry. If you don’t provide a slug then one will be automatically generated.
yml_distill_opts categories A character vector, the post categories
yml_distill_opts listing The listing a post is under; either a character vector, the output of distill_listing(), or a named list.
yml_distill_opts collection Specify the RSS, sharing, and other settings of a listing; use distill_collection() or a named list.
yml_distill_opts preview a path or link to the preview image for your article. You can also set this by including preview = TRUE in an R Markdown code chunk in your document.
yml_distill_opts repository_url A URL where the source code for your article can be found
yml_distill_opts citation_url A URL to the article; automatically generated for blog articles
yml_distill_opts compare_updates_url a URL that will show the differences between the article’s current version and the version that was initially published
yml_distill_opts base_url Base (root) URL for the location where the website will be deployed (used for providing preview images for Open Graph and Twitter Card)
yml_distill_opts creative_commons Designate articles that you create as Creative Commons licensed by specifying one of the standard Creative Commons licenses. Common options include “CC BY”, “CC BY-SA”, “CC BY-ND”, and “CC BY-NC”. See the distill vignette for more details.
yml_distill_opts twitter_site The Twitter handle for the site
yml_distill_opts twitter_creator The Twitter handle for the creator
yml_distill_opts journal_title The title of the journal
yml_distill_opts journal_issn The issn of the journal
yml_distill_opts journal_publisher The publisher of the journal
yml_distill_opts volume The volume the article is on
yml_distill_opts issue The issue the article is on
yml_distill_opts doi The article Digital Object Identifier (DOI)
yml_distill_opts resources Files to include or exclude while publishing. Use distill_resources() or a named list to specify.
yml_distill_opts url the author URL
yml_distill_opts affiliation_url the affiliation URL
yml_distill_opts listing_name A character vector, the name of the listing
yml_distill_opts slugs A character vector of the posts to include in the listing
yml_distill_opts collection_name A character vector, the name of the collection
yml_distill_opts feed_items_max Number of articles to include in the RSS feed (default: 20). Specify FALSE to have no limit on the number of items included in the feed.
yml_distill_opts disqus_name A shortname for the disqus comments section (base_url field is required in order to use Disqus)
yml_distill_opts disqus_hidden Logical. Show full text of disqus comments? By default, this is FALSE so as not to obscure the bibliography and other appendices.
yml_distill_opts share Share buttons to include. Choices: “twitter”, “linkedin”, “facebook”, “google-plus”, and “pinterest”. (base_url field is required in order to use sharing links)
yml_distill_opts citations Logical. If your _site.yml file provides a base_url field, an article citation appendix and related metadata will be included automatically within all published posts. Set to FALSE to disable this behavior.
yml_distill_opts subscribe a path to a HTML file enabling readers to subscribe. See the distill vignette on blog posts for more details.
yml_distill_opts include, exclude a character vector of files to explicitly include or exclude when publishing a post. Can use wild cards, such as "*.csv".

rticles YAML

rticles YAML
Help Page Argument Description
yml_rticles_opts title Title of the manuscript
yml_rticles_opts runninghead A character vector, a short author list for the header (sage_article)
yml_rticles_opts author A list of authors, containing name and num fields (sage_article, sim_article). Use rticles_author() or a list to specify.
yml_rticles_opts authormark A character vector, the short author list for the header (sim_article)
yml_rticles_opts address list containing num and org for defining author affiliations (sage_article, sim_article). Use rticles_address() or a list to specify.
yml_rticles_opts corrauth corresponding author name and address (sage_article). Use rticles_corr_author() or a list to specify.
yml_rticles_opts corres author and address for correspondence (sim_article). Use rticles_corr_author() or a list to specify.
yml_rticles_opts email The email of the correspondence author (sage_article)
yml_rticles_opts abstract The abstract, limited to 200 words (sage_article), 250 words (sim_article)
yml_rticles_opts received, revised, accepted The dates of submission, revision, and acceptance of the manuscript (sim_article)
yml_rticles_opts keywords The keywords for the article (sage_article), up to 6 keywords (sim_article)
yml_rticles_opts bibliography BibTeX .bib file name (sage_article, sim_article)
yml_rticles_opts longtable Logical. Include the longtable package? Used by default from pandoc to convert markdown to LaTeX code (sim_article)
yml_rticles_opts classoption a character vector of classoption options for the sagej class (sage_article)
yml_rticles_opts header_includes additional LaTeX code to include in the header, before the \\begin\{document\} statement (sage_article, sim_article). Note that the actual YAML field is header-includes
yml_rticles_opts include_after additional LaTeX code to include before the \\end\{document\} statement (sage_article, sim_article). Note that the actual YAML field is include-after.
yml_rticles_opts name The author’s name
yml_rticles_opts num The author’s number or address number
yml_rticles_opts org The author’s organization

RStudio Connect Scheduled Email YAML

RStudio Connect Scheduled Email YAML
Help Page Argument Description
yml_rsconnect_email rsc_email_subject The subject of the email. A report without an rsc_email_subject entry uses its published document name.
yml_rsconnect_email rsc_email_body_html, rsc_email_body_text The body of the email, either in plain text or HTML. A report with neither entry uses an automatically generated, plain-text body with a link to the report’s URL.
yml_rsconnect_email rsc_email_images Images to embed in the email. The embedded image must have a Content ID that is used in the body of the HTML and when providing the image to rsc_email_images, and the image itself must be base64-encoded, e.g. with the base64enc package.
yml_rsconnect_email rsc_output_files A vector of file names that should be available after the report has rendered. If you list a file that does not exist after rendering your report, Connect will log a message but continue trying to processing the other files listed. If the output files are not generated during the rendering of your report, then you will also need to list them in resource_files when you upload your report to Connect.
yml_rsconnect_email rsc_email_attachments A vector of file names that should be attached to the email.
yml_rsconnect_email rsc_email_suppress_scheduled Logical. Should the email schedule be suppressed? Default is FALSE.
yml_rsconnect_email rsc_email_suppress_report_attachment Logical. Should the rendered document be included as an attachment? Default is TRUE.
yml_rsconnect_email resource_files A file or files to host on RStudio Connect that is not generated by your report, e.g. an existing file.