Skip to contents

Metadata

Source: vignettes/metadata.Rmd
metadata.Rmd

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.

  • image: By default, pkgdown uses the package’s logo for the card image (if one exists). Use image to specify an alternative image for the social media cards of pages in your pkgdown site.

    • src: A fully qualified URL to a media card image e.g. src: https://avatars.githubusercontent.com/u/22618716?v=4; or a relative path to an image in the rendered website e.g. src: articles/test/image.jpg; or a relative path to an image stored in man/figures in the package e.g. src: man/figures/cards.png. The src field is required if image is specified.

    • alt: Alternative text describing the image for screen readers and other situations where your social media card image cannot be displayed.

  • twitter: You can specify the Twitter accounts associated with your package and the style of social media card that Twitter will display.

    • creator: Typically, the Twitter handle of the author of the package or article.

    • site: The Twitter handle of the organization affiliated with the package author or sponsoring the package development.

    • If only one of creator or site is included, the provided value will be used for both fields.

    • card: The style of social media card that Twitter will display. For pkgdown sites, the most relevant options are summary_large_image, featuring a large image over the page title and description, or summary, featuring a small square image inline and to the left of the page title and description.

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.

  • The title field is used as the title of your article in your pkgdown site and should always be included.

  • Both title and description are used by pkgdown for the page’s social media card. If description is not included in the article’s YAML front matter, then the name of the package is used instead. The description is also displayed on the articles index.

  • The author field is only used in the text of the vignette or article. How the author name is displayed depends on the output format.

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.