Skip to main content
Raw File Download
pkgdown.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>Introduction to pkgdown</title>

<script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
// be compatible with the behavior of Pandoc < 2.8).
document.addEventListener('DOMContentLoaded', function(e) {
  var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
  var i, h, a;
  for (i = 0; i < hs.length; i++) {
    h = hs[i];
    if (!/^h[1-6]$/i.test(h.tagName)) continue;  // it should be a header h1-h6
    a = h.attributes;
    while (a.length > 0) h.removeAttribute(a[0].name);
  }
});
</script>

<style type="text/css">
  code{white-space: pre-wrap;}
  span.smallcaps{font-variant: small-caps;}
  span.underline{text-decoration: underline;}
  div.column{display: inline-block; vertical-align: top; width: 50%;}
  div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
  ul.task-list{list-style: none;}
    </style>



<style type="text/css">
  code {
    white-space: pre;
  }
  .sourceCode {
    overflow: visible;
  }
</style>
<style type="text/css" data-origin="pandoc">
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > 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 {
pre > 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">Introduction to pkgdown</h1>



<p>The goal of pkgdown is to make it easy to make an elegant and useful
package website with a minimum of work. You can get a basic website up
and running in just a couple of minutes:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Run once to configure package to use pkgdown</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>usethis<span class="sc">::</span><span class="fu">use_pkgdown</span>()</span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="co"># Run to build the website</span></span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a>pkgdown<span class="sc">::</span><span class="fu">build_site</span>()</span></code></pre></div>
<p>If you’re using GitHub, we also recommend setting up GitHub actions
to automatically build and publish your site:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>usethis<span class="sc">::</span><span class="fu">use_pkgdown_github_pages</span>()</span></code></pre></div>
<p>While you’ll get a decent website without any additional work, if you
want a website that really pops, you’ll need to read the rest of this
vignette. It starts by showing you how to configure pkgdown with a
<code>_pkgdown.yml</code>. You’ll learn about the main components of the
site (the home page, reference, articles, and news), and then how to
publish and promote your site.</p>
<div id="metadata" class="section level2">
<h2>Metadata</h2>
<p>You can override pkgdown’s defaults with a YAML file called
<code>_pkgdown.yml</code><a href="#fn1" class="footnote-ref" id="fnref1"><sup>1</sup></a>. The most important field is
<code>url</code>, which gives the final location of the site:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="fu">url</span><span class="kw">:</span><span class="at"> https://pkgdown.r-lib.org</span></span></code></pre></div>
<p><code>url</code> is used throughout the site to generate absolute
urls where they are needed.</p>
<p>Another important option is <code>template</code>, which allows you
to control the overall appearance of your site:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="fu">template</span><span class="kw">:</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="fu">bootstrap</span><span class="kw">:</span><span class="at"> </span><span class="dv">5</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="fu">bootswatch</span><span class="kw">:</span><span class="at"> cerulean</span></span></code></pre></div>
<p>You can learn more about controlling the appearance of your site in
<code>vignette(&quot;customise&quot;)</code>.</p>
<div id="language" class="section level3">
<h3>Language</h3>
<p>If your documentation (<code>.Rd</code> and <code>.Rmd</code>) is
written in a language other than English, declare it by setting setting
<code>lang</code> to the <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">two letter
language code</a> for your language:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="fu">lang</span><span class="kw">:</span><span class="at"> fr</span></span></code></pre></div>
<p>This will be used to set the language of the web page and to
translate the English words that pkgdown generates on your site. Current
available translations are:</p>
<ul>
<li><code>de</code>: German</li>
<li><code>dk</code>: Danish</li>
<li><code>es</code>: Spanish</li>
<li><code>fr</code>: French</li>
<li><code>ko</code>: Korean</li>
<li><code>pt</code>: Portuguese</li>
<li><code>tr</code>: Turkish</li>
<li><code>zh_CN</code>: Chinese (simplified)</li>
</ul>
</div>
</div>
<div id="home-page" class="section level2">
<h2>Home page</h2>
<p>The contents of home page are automatically generated from
<code>index.md</code> or <code>README.md</code>. pkgdown tries them in
order, so it’s possible to have a different display on GitHub and
pkgdown by providing both files. The homepage also includes a sidebar
full of useful links; see <code>?build_home</code> for how these are
generated and how you can customise them.</p>
</div>
<div id="reference" class="section level2">
<h2>Reference</h2>
<p>pkgdown creates a function reference in <code>reference/</code> that
includes one page for each <code>.Rd</code> help topic in
<code>man/</code>. The translation of individual help topics from Rd to
HTML is generally straightforward, but there are a couple of things you
should bear in mind:</p>
<ul>
<li><p>pkgdown does its best to autolink all references to help topics
and articles described in <code>vignette(&quot;linking&quot;)</code>.</p></li>
<li><p>pkgdown executes all examples, inserting the rendered results in
the generated HTML files.</p></li>
</ul>
<p>By default, pkgdown generates a reference index that is just an
alphabetically-ordered list of functions. The index is much more useful
with human curation because functions can be grouped and described in
categories. To override the default, provide a <code>reference</code>
field in <code>_pkgdown.yml</code>.</p>
<p>Each entry in <code>reference</code> can take one of three forms:</p>
<ul>
<li>A title, defined by <code>title</code> and optional
<code>desc</code> (description) fields.</li>
<li>A subtitle, defined by <code>subtitle</code> and optional
<code>desc</code> (description) fields.</li>
<li>A list of topics defined by a <code>contents</code> field.</li>
</ul>
<div class="sourceCode" id="cb6"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="fu">reference</span><span class="kw">:</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="kw">-</span><span class="at"> </span><span class="fu">title</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;Connecting to Spark&quot;</span></span>
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a><span class="fu">  desc</span><span class="kw">: </span><span class="ch">&gt;</span></span>
<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a>    Functions for installing Spark components and managing</span>
<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a>    connections to Spark</span>
<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="fu">contents</span><span class="kw">:</span><span class="at"> </span></span>
<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="kw">-</span><span class="at"> spark_config</span></span>
<span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="kw">-</span><span class="at"> spark_connect</span></span>
<span id="cb6-9"><a href="#cb6-9" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="kw">-</span><span class="at"> spark_disconnect</span></span>
<span id="cb6-10"><a href="#cb6-10" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="kw">-</span><span class="at"> spark_install</span></span>
<span id="cb6-11"><a href="#cb6-11" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="kw">-</span><span class="at"> spark_log</span></span>
<span id="cb6-12"><a href="#cb6-12" aria-hidden="true" tabindex="-1"></a><span class="kw">-</span><span class="at"> </span><span class="fu">title</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;Reading and Writing Data&quot;</span></span>
<span id="cb6-13"><a href="#cb6-13" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="fu">desc</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;Functions for reading and writing Spark DataFrames.&quot;</span></span>
<span id="cb6-14"><a href="#cb6-14" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="fu">contents</span><span class="kw">:</span></span>
<span id="cb6-15"><a href="#cb6-15" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="kw">-</span><span class="at"> starts_with(&quot;spark_read&quot;)</span></span>
<span id="cb6-16"><a href="#cb6-16" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="kw">-</span><span class="at"> starts_with(&quot;spark_write&quot;)</span></span>
<span id="cb6-17"><a href="#cb6-17" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="kw">-</span><span class="at"> matches(&quot;saveload&quot;)</span></span></code></pre></div>
<p>Note the use of <code>starts_with()</code> to select all functions
with a common prefix. You can also use <code>ends_with()</code> and
<code>matches()</code>. See complete details in
<code>?build_reference</code>.</p>
<p>While iterating on the reference index you might want to run
<code>pkgdown::build_reference_index()</code>. It just re-builds the
index page, making it faster to quickly change
<code>_pkgdown.yaml</code> and see how it affects your site.</p>
</div>
<div id="articles" class="section level2">
<h2>Articles</h2>
<p>pkgdown will automatically build all vignettes found in
<code>vignettes/</code>, translating them to HTML files in
<code>articles/</code>. Due to the way that pkgdown has to integrate
RMarkdown generated HTML with its own HTML, relatively little control is
available over the output format. You can see the details in
<code>?build_articles</code>.</p>
<p>If you want to include an article on the website but not in the
package (e.g., because it’s large), you can either place it in a
subdirectory of <code>vignettes/</code>
(e.g. <code>vignettes/web_only</code>) or add it to
<code>.Rbuildignore</code> (and make sure that there’s no
<code>vignettes:</code> section in the yaml header). In the extreme case
where you want to produce only articles but not vignettes, you should
add the complete <code>vignettes/</code> directory to
<code>.Rbuildignore</code> and ensure that DESCRIPTION does not have a
<code>VignetteBuilder</code> field.</p>
</div>
<div id="news" class="section level2">
<h2>News</h2>
<p>If <code>NEWS.md</code> is present, it will be rendered into a
single-page changelog based on markdown level headings. pkgdown assumes
your <code>NEWS.md</code> is formatted using level one headings
(<code>#</code>) to specify package name and version number, and level
two headings (<code>##</code>) to provide topical organization for each
release.</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="fu"># pkgdown 1.1.0</span></span>
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a><span class="fu">## Bug Fixes</span></span>
<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a><span class="ss">* </span>Lots of them</span>
<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a><span class="fu"># pkgdown 1.0.0</span></span>
<span id="cb7-8"><a href="#cb7-8" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb7-9"><a href="#cb7-9" aria-hidden="true" tabindex="-1"></a><span class="ss">* </span>This is the first release of pkgdown.</span></code></pre></div>
<p>See more suggestions for writing news bullets in the <a href="https://style.tidyverse.org/news.html">tidyverse style
guide</a>.</p>
<p>See <code>?build_news</code> for more customisation options including
how to:</p>
<ul>
<li>Create one page for each major version and related minor
versions.</li>
<li>Add release announcements to the news navbar drop-down.</li>
</ul>
</div>
<div id="publishing" class="section level2">
<h2>Publishing</h2>
<p>If you use GitHub, there are two ways to publish your site on GitHub
Pages:</p>
<ul>
<li><p>Build the site locally, check in the docs directory, then
configure GitHub Pages to <a href="https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site">use
that directory</a>.</p></li>
<li><p>Use GitHub actions to automatically build and publish the site
every time you make a change. The easiest way to set this up is to run
<code>usethis::use_pkgdown_github_pages()</code>.</p></li>
</ul>
</div>
<div id="promoting" class="section level2">
<h2>Promoting</h2>
<p>Once your finalized site is built and published on the web, you
should publicize its URL in a few places:</p>
<ol style="list-style-type: decimal">
<li><p>The <code>URL</code> field of your package
<code>DESCRIPTION</code>, alongside a link to its source:</p>
<pre><code>URL: https://pkgdown.r-lib.org, https://github.com/r-lib/pkgdown</code></pre>
<p>(<code>usethis::use_pkgdown_github_pages()</code> does this for
you.)</p></li>
<li><p>Your repository description on GitHub.</p></li>
<li><p>On Twitter (make sure to include <code>#rstats</code>).</p></li>
</ol>
</div>
<div class="footnotes footnotes-end-of-document">
<hr />
<ol>
<li id="fn1"><p>You can also put it in <code>pkgdown/_pkgdown.yml</code>
if you want to keep the package root clutter-free, or in
<code>inst/_pkgdown.yml</code> if you want to make it available when
your package is installed.<a href="#fnref1" class="footnote-back">↩︎</a></p></li>
</ol>
</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>