metadata.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Metadata</title>
<style type="text/css">code{white-space: pre;}</style>
<style type="text/css" data-origin="pandoc">
code.sourceCode > span { display: inline-block; line-height: 1.25; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode { white-space: pre; position: relative; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
code.sourceCode { white-space: pre-wrap; }
code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
var sheets = document.styleSheets;
for (var i = 0; i < sheets.length; i++) {
if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
try { var rules = sheets[i].cssRules; } catch (e) { continue; }
for (var j = 0; j < rules.length; j++) {
var rule = rules[j];
// check if there is a div.sourceCode rule
if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") continue;
var style = rule.style.cssText;
// check if color or background-color is set
if (rule.style.color === '' && rule.style.backgroundColor === '') continue;
// replace div.sourceCode by a pre.sourceCode rule
sheets[i].deleteRule(j);
sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
}
}
})();
</script>
<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap;
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }
code > span.kw { color: #555; font-weight: bold; }
code > span.dt { color: #902000; }
code > span.dv { color: #40a070; }
code > span.bn { color: #d14; }
code > span.fl { color: #d14; }
code > span.ch { color: #d14; }
code > span.st { color: #d14; }
code > span.co { color: #888888; font-style: italic; }
code > span.ot { color: #007020; }
code > span.al { color: #ff0000; font-weight: bold; }
code > span.fu { color: #900; font-weight: bold; }
code > span.er { color: #a61717; background-color: #e3d2d2; }
</style>
</head>
<body>
<h1 class="title toc-ignore">Metadata</h1>
<p>Package authors can customize the metadata used by Twitter and the <a href="https://ogp.me/">Open Graph protocol</a> 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 card used on Twitter.</p>
<p>You can preview and validate the appearance of the social media cards with online tools:</p>
<ul>
<li><a href="https://cards-dev.twitter.com/validator">Twitter Card Validator</a></li>
<li><a href="https://search.google.com/structured-data/testing-tool">Google Structured Data Testing Tool</a></li>
</ul>
<div id="site-wide-customization" class="section level2">
<h2>Site-wide customization</h2>
<p>Metadata for the entire pkgdown website can be specified in the site’s <code>_pkgdown.yml</code> configuration file in the <code>home</code> and <code>template: opengraph</code> sections:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb1-1"><a href="#cb1-1"></a><span class="fu">home</span><span class="kw">:</span></span>
<span id="cb1-2"><a href="#cb1-2"></a><span class="at"> </span><span class="fu">title</span><span class="kw">:</span><span class="at"> An R package for pool-noodle discovery</span></span>
<span id="cb1-3"><a href="#cb1-3"></a><span class="at"> </span><span class="fu">description</span><span class="kw">:</span><span class="at"> Discover and add pool-noodles to your growing collection.</span></span>
<span id="cb1-4"><a href="#cb1-4"></a><span class="at"> </span></span>
<span id="cb1-5"><a href="#cb1-5"></a><span class="fu">template</span><span class="kw">:</span></span>
<span id="cb1-6"><a href="#cb1-6"></a><span class="at"> </span><span class="fu">opengraph</span><span class="kw">:</span></span>
<span id="cb1-7"><a href="#cb1-7"></a><span class="at"> </span><span class="fu">image</span><span class="kw">:</span></span>
<span id="cb1-8"><a href="#cb1-8"></a><span class="at"> </span><span class="fu">src</span><span class="kw">:</span><span class="at"> man/figures/card.png</span></span>
<span id="cb1-9"><a href="#cb1-9"></a><span class="at"> </span><span class="fu">alt</span><span class="kw">:</span><span class="at"> </span><span class="st">"Pool noodles configured to form the word poolnoodlr"</span></span>
<span id="cb1-10"><a href="#cb1-10"></a><span class="at"> </span><span class="fu">twitter</span><span class="kw">:</span></span>
<span id="cb1-11"><a href="#cb1-11"></a><span class="at"> </span><span class="fu">creator</span><span class="kw">:</span><span class="at"> </span><span class="st">"@hadleywickham"</span></span>
<span id="cb1-12"><a href="#cb1-12"></a><span class="at"> </span><span class="fu">site</span><span class="kw">:</span><span class="at"> </span><span class="st">"@rstudio"</span></span>
<span id="cb1-13"><a href="#cb1-13"></a><span class="at"> </span><span class="fu">card</span><span class="kw">:</span><span class="at"> summary_large_image</span></span></code></pre></div>
<p>The <code>home: title</code> and <code>home: description</code> fields override the <code>Title</code> and <code>Description</code> fields in the package <code>DESCRIPTION</code>. 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.</p>
<p>The <code>template: opengraph</code> section allows you to further customize the social media card.</p>
<ul>
<li><p><code>image</code>: By default, pkgdown uses the package’s logo for the card image (if one exists). Use <code>image</code> to specify an alternative image for the social media cards of pages in your pkgdown site.</p>
<ul>
<li><p><code>src</code>: A fully qualified URL to a media card image, or a relative path to an image stored in the package. The <code>src</code> field is required if <code>image</code> is specified.</p></li>
<li><p><code>alt</code>: Alternative text describing the image for screen readers and other situations where your social media card image cannot be displayed.</p></li>
</ul></li>
<li><p><code>twitter</code>: You can specify the Twitter accounts associated with your package and the <a href="https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards">style of social media card</a> that Twitter will display.</p>
<ul>
<li><p><code>creator</code>: Typically, the Twitter handle of the author of the package or article.</p></li>
<li><p><code>site</code>: The Twitter handle of the organization affiliated with the package author or sponsoring the package development.</p></li>
<li><p>If only one of <code>creator</code> or <code>site</code> are included, the provided value will be used for both fields.</p></li>
<li><p><code>card</code>: The <a href="https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards">style of social media card</a> that Twitter will display. For pkgdown sites, the most relevant options are <code>summary_large_image</code>, featuring a large image over the page title and description, or <code>summary</code>, featuring a small square image inline and to the left of the page title and description.</p></li>
</ul></li>
</ul>
</div>
<div id="article-metadata" class="section level2">
<h2>Article metadata</h2>
<p>Articles and vignettes rendered as articles by pkgdown can have individually customized metadata and social media cards.</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb2-1"><a href="#cb2-1"></a><span class="fu">title</span><span class="kw">:</span><span class="at"> </span><span class="st">"Introduction to poolnoodlr"</span></span>
<span id="cb2-2"><a href="#cb2-2"></a><span class="fu">description</span><span class="kw">:</span><span class="at"> </span><span class="st">"A brief introduction to pool noodles in R."</span></span>
<span id="cb2-3"><a href="#cb2-3"></a><span class="fu">author</span><span class="kw">:</span><span class="at"> </span><span class="st">"Mara Averick"</span></span>
<span id="cb2-4"><a href="#cb2-4"></a><span class="fu">opengraph</span><span class="kw">:</span></span>
<span id="cb2-5"><a href="#cb2-5"></a><span class="at"> </span><span class="fu">image</span><span class="kw">:</span><span class="at"> </span></span>
<span id="cb2-6"><a href="#cb2-6"></a><span class="at"> </span><span class="fu">src</span><span class="kw">:</span><span class="at"> </span><span class="st">"http://example.com/pkg/batpig.png"</span></span>
<span id="cb2-7"><a href="#cb2-7"></a><span class="at"> </span><span class="fu">twitter</span><span class="kw">:</span></span>
<span id="cb2-8"><a href="#cb2-8"></a><span class="at"> </span><span class="fu">card</span><span class="kw">:</span><span class="at"> summary</span></span>
<span id="cb2-9"><a href="#cb2-9"></a><span class="at"> </span><span class="fu">creator</span><span class="kw">:</span><span class="at"> </span><span class="st">"@dataandme"</span></span>
<span id="cb2-10"><a href="#cb2-10"></a><span class="fu">output</span><span class="kw">:</span><span class="at"> rmarkdown::html_vignette</span></span>
<span id="cb2-11"><a href="#cb2-11"></a><span class="fu">vignette</span><span class="kw">: </span><span class="ch">></span></span>
<span id="cb2-12"><a href="#cb2-12"></a> %\VignetteIndexEntry{Introduction to poolnoodlr}</span>
<span id="cb2-13"><a href="#cb2-13"></a> %\VignetteEngine{knitr::rmarkdown}</span>
<span id="cb2-14"><a href="#cb2-14"></a> %\VignetteEncoding{UTF-8}</span></code></pre></div>
<p>Use the <code>title</code>, <code>description</code>, and <code>author</code> fields to specify the title, description, and (optional) author of the vignette or article.</p>
<ul>
<li><p>The <code>title</code> field is used as the title of your article in your pkgdown site and should always be included.</p></li>
<li><p>Both <code>title</code> and <code>description</code> are used by pkgdown for the page’s social media card. If <code>description</code> is not included in the article’s YAML front matter, then the name of the package is used instead. The <code>description</code> is also displayed on the articles index.</p></li>
<li><p>The <code>author</code> field is only used in the text of the vignette or article. How the author name is displayed depends on the <code>output</code> format.</p></li>
</ul>
<p>In articles, the <code>opengraph</code> section works in the same way as the site-wide <code>template: opengraph</code> 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 <code>opengraph</code> settings from the site-wide configuration are used.</p>
</div>
<!-- code folding -->
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
document.getElementsByTagName("head")[0].appendChild(script);
})();
</script>
</body>
</html>
