yml_distill_opts: Set Top-level YAML options for distill
In r-lib/ymlthis: Write 'YAML' for 'R Markdown', 'bookdown', 'blogdown', and More

yml_distill_opts

R Documentation

Set Top-level YAML options for distill

Description

distill uses many custom YAML fields to create some of its unique features, such as article metadata and citations. In addition to the arguments in yml_distill_opts(), ymlthis supports distill in a number of other ways. yml_distill_author() wraps yml_author() to include these extra used in distill. For a distill blog, you can specify the listings page a post belongs to, including an optional vector of other posts to list with it; distill_listing() is a helper function to pass to the listing argument to specify such pages. distill uses the same approach to navbars as R Markdown. yml_navbar() and friends will help you write the YAML for that. YAML specifying the site build, like the output field and navbars, can also be placed in _site.yml; see yml_site_opts() for further R Markdown website build options and use_site_yml() for creating that file based on a yml object. distill's YAML options are discussed in greater detail in the articles on the distill website.

Usage

yml_distill_opts(
  .yml,
  draft = yml_blank(),
  slug = yml_blank(),
  categories = yml_blank(),
  listing = yml_blank(),
  collection = yml_blank(),
  citation_url = yml_blank(),
  preview = yml_blank(),
  repository_url = yml_blank(),
  base_url = yml_blank(),
  compare_updates_url = yml_blank(),
  creative_commons = yml_blank(),
  twitter_site = yml_blank(),
  twitter_creator = yml_blank(),
  journal_title = yml_blank(),
  journal_issn = yml_blank(),
  journal_publisher = yml_blank(),
  volume = yml_blank(),
  issue = yml_blank(),
  doi = yml_blank(),
  resources = yml_blank(),
  ...
)

yml_distill_author(
  .yml,
  name = yml_blank(),
  url = yml_blank(),
  affiliation = yml_blank(),
  affiliation_url = yml_blank(),
  orcid_id = yml_blank()
)

distill_listing(listing_name = "posts", slugs = NULL)

distill_collection(
  collection_name = "post",
  feed_items_max = yml_blank(),
  disqus_name = yml_blank(),
  disqus_hidden = yml_blank(),
  share = yml_blank(),
  citations = yml_blank(),
  subscribe = yml_blank()
)

distill_resources(include = yml_blank(), exclude = yml_blank())

Arguments

`.yml`	a `yml` object created by `yml()`, `as_yml()`, or returned by a `yml_*()` function
`draft`	Logical. Set the post to be a draft? Draft posts won't be published.
`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.
`categories`	A character vector, the post categories
`listing`	The listing a post is under; either a character vector, the output of `distill_listing()`, or a named list.
`collection`	Specify the RSS, sharing, and other settings of a listing; use `distill_collection()` or a named list.
`citation_url`	A URL to the article; automatically generated for blog articles
`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.
`repository_url`	A URL where the source code for your article can be found
`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)
`compare_updates_url`	a URL that will show the differences between the article’s current version and the version that was initially published
`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.
`twitter_site`	The Twitter handle for the site
`twitter_creator`	The Twitter handle for the creator
`journal_title`	The title of the journal
`journal_issn`	The issn of the journal
`journal_publisher`	The publisher of the journal
`volume`	The volume the article is on
`issue`	The issue the article is on
`doi`	The article Digital Object Identifier (DOI)
`resources`	Files to include or exclude while publishing. Use `distill_resources()` or a named list to specify.
`...`	additional named R objects, such as characters or lists, to transform into YAML
`name`	A character vector, name of the author(s)
`url`	the author URL
`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.
`affiliation_url`	the affiliation URL
`orcid_id`	the author's ORCID ID
`listing_name`	A character vector, the name of the listing
`slugs`	A character vector of the posts to include in the listing
`collection_name`	A character vector, the name of the collection
`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.
`disqus_name`	A shortname for the disqus comments section (`base_url` field is required in order to use Disqus)
`disqus_hidden`	Logical. Show full text of disqus comments? By default, this is `FALSE` so as not to obscure the bibliography and other appendices.
`share`	Share buttons to include. Choices: "twitter", "linkedin", "facebook", "google-plus", and "pinterest". (`base_url` field is required in order to use sharing links)
`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.
`subscribe`	a path to a HTML file enabling readers to subscribe. See the distill vignette on blog posts for more details.
`include, exclude`	a character vector of files to explicitly include or exclude when publishing a post. Can use wild cards, such as "*.csv".

Value

a yml object

Examples

post_listing <- distill_listing(
  slugs = c(
    "2016-11-08-sharpe-ratio",
    "2017-11-09-visualizing-asset-returns",
    "2017-09-13-asset-volatility"
  )
)

yml() %>%
  yml_title("Gallery of featured posts") %>%
  yml_distill_opts(listing = post_listing)

yml_empty() %>%
  yml_title("Reproducible Finance with R") %>%
  yml_description("Exploring reproducible finance with the R statistical,
  computing environment.") %>%
  yml_site_opts(name = "reproducible-finance-with-r") %>%
  yml_distill_opts(
    base_url = "https://beta.rstudioconnect.com/content/3776/",
    collection = distill_collection(
      feed_items_max = 30,
      disqus_name = "reproducible-finance-with-r",
      disqus_hidden = FALSE,
      share = c("twitter", "linkedin")
    )
  )

r-lib/ymlthis documentation built on Aug. 7, 2022, 12:10 a.m.