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:
Metadata can only be produced correctly if your pkgdown website URL is indicated in its configuration file.
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_imageThe 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.
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.