Set Top-level YAML options for distill

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.

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

See also

use_site_yml() use_rmarkdown()

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_bookdown_opts(), yml_citations(), yml_clean(), 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 websites: yml_pkgdown(), yml_site_opts()

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)
#> ---
#> date: '`r format(Sys.Date())`'
#> title: Gallery of featured posts
#> listing:
#>   posts:
#>   - 2016-11-08-sharpe-ratio
#>   - 2017-11-09-visualizing-asset-returns
#>   - 2017-09-13-asset-volatility
#> ---
#> 

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")
    )
  )
#> ---
#> title: Reproducible Finance with R
#> description: |-
#>   Exploring reproducible finance with the R statistical,
#>     computing environment.
#> name: reproducible-finance-with-r
#> collection:
#>   post:
#>     feed_items_max: 30.0
#>     disqus:
#>       shortname: reproducible-finance-with-r
#>       hiden: false
#>     share:
#>     - twitter
#>     - linkedin
#> base_url: https://beta.rstudioconnect.com/content/3776/
#> ---
#>