Metadata

Package authors can customize the metadata used by Twitter and the Open Graph protocol for rich social media cards. In addition to specifying an alternate description for the package and any individual articles, you may also choose the preview image shown and the style of the card used on Twitter.

You can preview and validate the appearance of the social media cards with online tools:

Necessary configuration

Metadata can only be produced correctly if your pkgdown website URL is indicated in its configuration file.

url: https://example.com

Site-wide customization

Metadata for the entire pkgdown website can be specified in the site’s _pkgdown.yml configuration file in the home and template: opengraph sections:

home:
  title: An R package for pool-noodle discovery
  description: Discover and add pool-noodles to your growing collection.

template:
  opengraph:
    image:
      src: man/figures/card.png
      alt: "Pool noodles configured to form the word poolnoodlr"
    twitter:
      creator: "@hadleywickham"
      site: "@rstudio"
      card: summary_large_image

The home: title and home: description fields override the Title and Description fields in the package DESCRIPTION. It’s good practice to set these fields to make your package documentation easier to find via search, rather than sticking with the title and description needed by CRAN.

The template: opengraph section allows you to further customize the social media card.

Article metadata

Articles and vignettes rendered as articles by pkgdown can have individually customized metadata and social media cards.

title: "Introduction to poolnoodlr"
description: "A brief introduction to pool noodles in R."
author: "Mara Averick"
opengraph:
  image:
    src: "https://example.com/pkg/batpig.png"
  twitter:
    card: summary
    creator: "@dataandme"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to poolnoodlr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}

Use the title, description, and author fields to specify the title, description, and (optional) author of the vignette or article.

In articles, the opengraph section works in the same way as the site-wide template: opengraph settings, but is only applied to the article or vignette. This allows you to specify social media card preview images for individual articles, or to associate an article with a particular Twitter account. If not specified, the opengraph settings from the site-wide configuration are used.