``` r
# Install development version from GitHub
devtools::install_github("r-lib/pkgdown")
```
## Usage
Get started with [usethis](https://usethis.r-lib.org/):
``` r
# Run once to configure your package to use pkgdown
usethis::use_pkgdown()
```
Then use pkgdown to build your website:
``` r
pkgdown::build_site()
```
This generates a `docs/` directory containing a website. Your
`README.md` becomes the homepage, documentation in `man/` generates a
function reference, and vignettes will be rendered into `articles/`.
Read `vignette("pkgdown")` for more details, and to learn how to deploy
your site to GitHub pages.
### pkgdown 2.0.0 and Bootstrap 5
pkgdown 2.0.0 includes an upgrade from Bootstrap 3 to Bootstrap 5, which
is accompanied by a whole bunch of minor UI improvements. If you’ve
heavily customised your site, there’s a small chance that this will
break your site, so everyone needs to explicitly opt-in to the upgrade
by adding the following to `_pkgdown.yml`:
``` yaml
template:
bootstrap: 5
```
Then learn about the many new ways to customise your site in
`vignette("customise")`.
## In the wild
At last count, pkgdown is used [by over 6,000
packages](https://github.com/search?q=filename%3Apkgdown.yml+path%3A%2F&type=Code).
Here are a few examples created by contributors to pkgdown:
- [bayesplot](http://mc-stan.org/bayesplot/index.html)
([source](https://github.com/stan-dev/bayesplot/tree/gh-pages)):
plotting functions for posterior analysis, model checking, and MCMC
diagnostics.
- [valr](https://rnabioco.github.io/valr/)
([source](https://github.com/rnabioco/valr)): read and manipulate
genome intervals and signals.
- [mkin](https://pkgdown.jrwb.de/mkin/)
([source](https://github.com/jranke/mkin)): calculation routines based
on the FOCUS Kinetics Report
- [NMF](http://renozao.github.io/NMF/master/index.html)
([source](https://github.com/renozao/NMF)): a framework to perform
non-negative matrix factorization (NMF).
Comparing the source and output of these sites is a great way to learn
new pkgdown techniques.
## Code of conduct
Please note that this project is released with a [Contributor Code of
Conduct](https://pkgdown.r-lib.org/CODE_OF_CONDUCT.html). By
participating in this project you agree to abide by its terms.
pkgdown/man/ 0000755 0001762 0000144 00000000000 14343702121 012473 5 ustar ligges users pkgdown/man/build_search.Rd 0000644 0001762 0000144 00000002126 14247740574 015430 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build-search-docs.R
\name{build_search}
\alias{build_search}
\title{Build search index}
\usage{
build_search(pkg = ".", override = list())
}
\arguments{
\item{pkg}{Path to package.}
\item{override}{An optional named list used to temporarily override
values in \verb{_pkgdown.yml}}
}
\description{
Build a JSON file encompassing all HTML pages, for use by the search script.
}
\section{YAML config}{
You can exclude some paths from the search index.
Below we exclude the changelog from the search index.
\if{html}{\out{} syntax to control
where a block of markdown will display. For example, you can use the
following markdown in your README to only show GitHub install instructions
on the development version of your site:
\if{html}{\out{
}}\preformatted{::: \{.pkgdown-devel\}
You can install the development version of pkgdown from GitHub with:
`remotes::install_github("r-lib/pkgdown")`
:::
}\if{html}{\out{
}}
You can use a similar technique to control where badges are displayed.
This markdown show the CRAN status badge on the site for the released
package and the GitHub check status for the development package:
\if{html}{\out{
}}\preformatted{[]
(https://cran.r-project.org/package=pkgdown)\{.pkgdown-release\}
[]
(https://github.com/r-lib/pkgdown/actions)\{.pkgdown-devel\}
}\if{html}{\out{
}}
}
\subsection{Other options}{
There are three other options that you can control:
\if{html}{\out{
}}\preformatted{development:
destination: dev
version_label: danger
version_tooltip: "Custom message here"
}\if{html}{\out{
}}
\code{destination} allows you to override the default subdirectory used for the
development site; it defaults to \verb{dev/}. \code{version_label} allows you to
override the style used for development (and unreleased) versions of the
package. It defaults to "danger", but you can set to "default", "info", or
"warning" instead. (The precise colours are determined by your bootstrap
theme, but become progressively more eye catching as you go from default
to danger). Finally, you can choose to override the default tooltip with
\code{version_tooltip}.
}
}
\section{Navigation bar}{
You can customise the navigation bar that appears at the top of the page with the \code{navbar} field.
It's made up of two pieces: \code{structure}, which defines the overall layout, and \code{components}, which defines what each piece looks like.
This organisation makes it easy to mix and match pkgdown defaults with your own customisations.
This is the default structure:
\if{html}{\out{
}}\preformatted{navbar:
structure:
left: [intro, reference, articles, tutorials, news]
right: [search, github]
}\if{html}{\out{
}}
It makes use of the the six built-in components:
\itemize{
\item \code{intro}: "Get Started", which links to a vignette with the same name as the package.
\item \code{reference}, if there are any \code{.Rd} files.
\item \code{articles}, if there are any vignettes or articles.
\item \code{tutorials}, if there any tutorials.
\item \code{news}, if \code{NEWS.md} exists.
\item \code{search}, the search box (see \code{vignette("search")} for more details).
\item \code{github}, a link to the source repository (with an icon), if it can be automatically determined from the \code{DESCRIPTION}.
}
You can use the \code{structure} field to reorganise the navbar without changing the default contents:
\if{html}{\out{
}}\preformatted{navbar:
structure:
left: [search]
right: [reference, articles]
}\if{html}{\out{
}}
You can use \code{components} to override the default content.
For example, this yaml provides a custom articles menu:
\if{html}{\out{
}}\preformatted{navbar:
components:
articles:
text: Articles
menu:
- text: Category A
- text: Title A1
href: articles/a1.html
- text: Title A2
href: articles/a2.html
- text: -------
- text: "Category B"
- text: Article B1
href: articles/b1.html
}\if{html}{\out{
}}
Components uses the same syntax as \href{https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html#site-navigation}{RMarkdown menus}.
The elements of \code{menu} can be:
\itemize{
\item A link (\code{text} + \code{href})
\item A heading (just \code{text})
\item A separator (\verb{text: ——–})
}
Instead of text, you can also use the name of an \code{icon}s from \href{https://fontawesome.com/icons?d=gallery}{fontawesome}.
You should also provide a textual description in the \code{aria-label} field for screenreader users.
To add a new component to the navbar, you need to modify both \code{structure} and \code{components}.
For example, the following yaml adds a new "twitter" component that appears to the left of the github icon.
\if{html}{\out{
}}\preformatted{navbar:
structure:
right: [twitter, github]
components:
twitter:
icon: fa-twitter
href: http://twitter.com/hadleywickham
aria-label: Twitter
}\if{html}{\out{
}}
Finally, you can add arbitrary HTML to three locations in the navbar:
\if{html}{\out{
}}\preformatted{template:
includes:
before_title:
after_navbar:
}\if{html}{\out{
}}
These includes will appear on all screen sizes, and will not be collapsed into the the navbar drop down.
You can also customise the colour scheme of the navbar by using the \code{type}
and \code{bg} parameters. See \code{vignette("customise")} for more details.
}
\section{Footer}{
You can customise the footer with the \code{footer} field.
It's made up of two pieces: \code{structure}, which defines the overall layout, and \code{components}, which defines what each piece looks like.
This organisation makes it easy to mix and match the pkgdown defaults with your own customisations.
This is the default structure:
\if{html}{\out{
}}\preformatted{footer:
structure:
left: developed_by
right: built_with
}\if{html}{\out{
}}
Which uses two of the three built-in components:
\itemize{
\item \code{developed_by}, a sentence describing the main authors of the package. (See \code{?build_home} if you want to tweak \emph{which} authors appear in the footer.)
\item \code{built_with}, a sentence advertising pkgdown.
\item \code{package}, the name of the package.
}
You can override these defaults with the \code{footer} field.
The example below puts the authors' information on the right along with a legal disclaimer, and puts the pkgdown link on the left.
\if{html}{\out{
}}\preformatted{footer:
structure:
left: pkgdown
right: [authors, legal]
components:
legal: Provided without **any warranty**.
}\if{html}{\out{
}}
Each side is pasted into a single string (separated by \code{" "}) and then converted from markdown to HTML.
}
\section{Search}{
The \code{search} field controls the built-in search. See \code{vignette("search")}
for details.
}
\section{Template}{
The \code{template} field is mostly used to control the appearance of the site.
See \code{vignette("customise")} for details.
There are two other \code{template} fields that control other aspects of the
site:
\itemize{
\item \code{noindex: true} will suppress indexing of your pages by search engines:
\if{html}{\out{
}}\preformatted{template:
params:
noindex: true
}\if{html}{\out{
}}
\item \code{google_site_verification} allows you to verify your site with google:
\if{html}{\out{
}}\preformatted{template:
params:
google_site_verification: _nn6ile-a6x6lctOW
}\if{html}{\out{
}}
\item \code{trailing_slash_redirect: true} will automatically redirect
\code{your-package-url.com} to \verb{your-package-url.com/}, using a JS script
added to the \verb{} of the home page. This is useful in certain
redirect scenarios.
\if{html}{\out{
}}\preformatted{template:
trailing_slash_redirect: true
}\if{html}{\out{
}}
}
}
\section{Analytics}{
To capture usage of your site with a web analytics platform, you can make
use of the \code{includes} field to add the HTML supplied to you by the platform.
Typically these are either placed \code{after_body} or \code{in_header}. I include
a few examples below, but I highly recommend getting the recommended HTML
directly from the platform.
\itemize{
\item \href{https://www.goatcounter.com}{GoatCounter}:
\if{html}{\out{
}}\preformatted{template:
includes:
after_body: >
}\if{html}{\out{
}}
\item \href{https://analytics.google.com/analytics/web/}{Google analytics}:
\if{html}{\out{
}}\preformatted{template:
includes:
in_header: |
}\if{html}{\out{
}}
\item \href{https://plausible.io}{plausible.io}:
\if{html}{\out{
}}\preformatted{templates:
includes:
in_header: |
}\if{html}{\out{
}}
}
}
\section{Source repository}{
Use the \code{repo} field to override pkgdown's automatically discovery
of your source repository. This is used in the navbar, on the homepage,
in articles and reference topics, and in the changelog (to link to issue
numbers and user names). pkgdown can automatically figure out the necessary
URLs if you link to a GitHub or GitLab repo in your \code{BugReports} or \code{URL}
field.
Otherwise, you can supply your own in the \code{repo} field:
\if{html}{\out{
}}\preformatted{repo:
url:
home: https://github.com/r-lib/pkgdown/
source: https://github.com/r-lib/pkgdown/blob/HEAD/
issue: https://github.com/r-lib/pkgdown/issues/
user: https://github.com/
}\if{html}{\out{
}}
\itemize{
\item \code{home}: path to package home on source code repository.
\item \verb{source:}: path to source of individual file in default branch.
\item \code{issue}: path to individual issue.
\item \code{user}: path to user.
}
The varying components (e.g. path, issue number, user name) are pasted on
the end of these URLs so they should have trailing \code{/}s.
pkgdown can automatically link to Jira issues as well if specify both a
custom \code{issue} URL as well Jira project names to auto-link in
\code{jira_projects}. You can specify as many projects as you would like:
\if{html}{\out{
}}\preformatted{repo:
jira_projects: [this_project, another_project]
url:
issue: https://jira.organisation.com/jira/browse/
}\if{html}{\out{
}}
pkgdown defaults to using the "HEAD" branch for source file URLs. This can
be configured to use a specific branch when linking to source files by
specifying a branch name:
\if{html}{\out{
}}\preformatted{repo:
branch: devel
}\if{html}{\out{
}}
}
\section{Deployment (\code{deploy})}{
There is a single \code{deploy} field
\itemize{
\item \code{install_metadata} allows you to install package index metadata into
the package itself. Normally this metadata is made available on the
published site; installing it into your package means that it's
available for autolinking even if your website is not reachable at build
time (e.g. because behind a firewall or requires auth).
\if{html}{\out{
}}\preformatted{deploy:
install_metadata: true
}\if{html}{\out{
}}
}
}
\section{Redirects}{
If you change the structure of your documentation (by renaming vignettes or help topics) you can setup redirects from the old content to the new content.
One or several now-absent pages can be redirected to a new page (or to a new section of a new page).
This works by creating a html page that performs a "meta refresh", which isn't the best way of doing a redirect but works everywhere that you might deploy your site.
The syntax is the following, with old paths on the left, and new paths or URLs on the right.
\if{html}{\out{
}}\preformatted{redirects:
- ["articles/old-vignette-name.html", "articles/new-vignette-name.html"]
- ["articles/another-old-vignette-name.html", "articles/new-vignette-name.html"]
- ["articles/yet-another-old-vignette-name.html", "https://pkgdown.r-lib.org/dev"]
}\if{html}{\out{
}}
If for some reason you choose to redirect an existing page make sure to exclude it from the search index, see \code{?build_search}.
}
\section{Options}{
Users with limited internet connectivity can disable CRAN checks by setting
\code{options(pkgdown.internet = FALSE)}. This will also disable some features
from pkgdown that requires an internet connectivity. However, if it is used
to build docs for a package that requires internet connectivity in examples
or vignettes, this connection is required as this option won't apply on them.
Users can set a timeout for \code{build_site(new_process = TRUE)} with
\code{options(pkgdown.timeout = Inf)}, which is useful to prevent stalled builds from
hanging in cron jobs.
}
\examples{
\dontrun{
build_site()
build_site(override = list(destination = tempdir()))
}
}
pkgdown/man/build_news.Rd 0000644 0001762 0000144 00000005171 14247740574 015142 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build-news.R
\name{build_news}
\alias{build_news}
\title{Build news section}
\usage{
build_news(pkg = ".", override = list(), preview = NA)
}
\arguments{
\item{pkg}{Path to package.}
\item{override}{An optional named list used to temporarily override
values in \verb{_pkgdown.yml}}
\item{preview}{If \code{TRUE}, or \code{is.na(preview) && interactive()}, will preview
freshly generated section in browser.}
}
\description{
A \code{NEWS.md} will be broken up into versions using level one (\verb{#}) or
level two headings (\verb{##}) that (partially) match one of the following forms
(ignoring case):
\itemize{
\item \verb{\{package name\} 1.3.0}
\item \verb{\{package name\} v1.3.0}
\item \verb{Version 1.3.0}
\item \verb{Changes in 1.3.0}
\item \verb{Changes in v1.3.0}
}
}
\details{
A \href{https://style.tidyverse.org/news.html}{common structure} for news files
is to use a top level heading for each release, and use a second level
heading to break up individual bullets into sections.
\if{html}{\out{
}}\preformatted{# foofy 1.0.0
## Major changes
* Can now work with all grooveable grobbles!
## Minor improvements and bug fixes
* Printing scrobbles no longer errors (@githubusername, #100)
* Wibbles are now 55\% less jibbly (#200)
}\if{html}{\out{
}}
Issues and contributors will be automatically linked to the corresponding
pages on GitHub if the GitHub repo can be discovered from the \code{DESCRIPTION}
(typically from a \code{URL} entry containing \code{github.com})
If a version is available on CRAN, the release date will automatically
be added to the heading (see below for how to suppress); if not
available on CRAN, "Unreleased" will be added.
}
\section{YAML config}{
To automatically link to release announcements, include a \code{releases}
section.
\if{html}{\out{
}}\preformatted{news:
releases:
- text: "usethis 1.3.0"
href: https://www.tidyverse.org/articles/2018/02/usethis-1-3-0/
- text: "usethis 1.0.0 (and 1.1.0)"
href: https://www.tidyverse.org/articles/2017/11/usethis-1.0.0/
}\if{html}{\out{
}}
Control whether news is present on one page or multiple pages with the
\code{one_page} field. The default is \code{true}.
\if{html}{\out{
}}\preformatted{news:
one_page: false
}\if{html}{\out{
}}
Suppress the default addition of CRAN release dates with:
\if{html}{\out{
}}\preformatted{news:
cran_dates: false
}\if{html}{\out{
}}
}
\seealso{
\href{https://style.tidyverse.org/news.html}{Tidyverse style for News}
}
pkgdown/man/render_page.Rd 0000644 0001762 0000144 00000002323 14247740574 015256 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/render.R
\name{render_page}
\alias{render_page}
\alias{data_template}
\title{Render page with template}
\usage{
render_page(pkg = ".", name, data, path, depth = NULL, quiet = FALSE)
data_template(pkg = ".", depth = 0L)
}
\arguments{
\item{pkg}{Path to package to document.}
\item{name}{Name of the template (e.g. "home", "vignette", "news")}
\item{data}{Data for the template.
This is automatically supplemented with three lists:
\itemize{
\item \code{site}: \code{title} and path to \code{root}.
\item \code{yaml}: the \code{template} key from \verb{_pkgdown.yml}.
\item \code{package}: package metadata including \code{name} and\code{version}.
}
See the full contents by running \code{\link[=data_template]{data_template()}}.}
\item{path}{Location to create file; relative to destination directory.}
\item{depth}{Depth of path relative to base directory.}
\item{quiet}{If \code{quiet}, will suppress output messages}
}
\description{
Each page is composed of four templates: "head", "header", "content", and
"footer". Each of these templates is rendered using the \code{data}, and
then assembled into an overall page using the "layout" template.
}
pkgdown/man/templates.Rd 0000644 0001762 0000144 00000001302 13632757251 014772 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/template.R
\name{template_navbar}
\alias{template_navbar}
\alias{template_reference}
\alias{template_articles}
\title{Generate YAML templates}
\usage{
template_navbar(path = ".")
template_reference(path = ".")
template_articles(path = ".")
}
\arguments{
\item{path}{Path to package root}
}
\description{
Use these function to generate the default YAML that pkgdown uses for
the different parts of \verb{_pkgdown.yml}. This are useful starting
points if you want to customise your site.
}
\examples{
\dontrun{
pkgdown::template_navbar()
}
\dontrun{
pkgdown::template_reference()
}
\dontrun{
pkgdown::template_articles()
}
}
pkgdown/man/test-long-lines.Rd 0000644 0001762 0000144 00000001352 14140057026 016011 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test.R
\name{test-long-lines}
\alias{test-long-lines}
\title{Test case: long-lines}
\description{
The example results should have the copy button correctly placed when
scrollings
}
\examples{
pkgdown:::ruler()
cat(rep("x ", 100), sep = "")
cat(rep("xy", 100), sep = "")
cat(rep("x ", 100), sep = "")
cat(rep("xy", 100), sep = "")
}
\seealso{
Other tests:
\code{\link{index}},
\code{\link{test-crayon}},
\code{\link{test-dont}},
\code{\link{test-figures}},
\code{\link{test-links}},
\code{\link{test-lists}},
\code{\link{test-output-styles}},
\code{\link{test-params}},
\code{\link{test-sexpr-title}},
\code{\link{test-verbatim}}
}
\concept{tests}
\keyword{internal}
pkgdown/man/fig_settings.Rd 0000644 0001762 0000144 00000001522 14264307402 015454 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/figure.R
\name{fig_settings}
\alias{fig_settings}
\title{Get current settings for figures}
\usage{
fig_settings()
}
\value{
A list containing the entries from the \code{figures} field in \verb{_pkgdown.yml}
(see \code{\link[=build_reference]{build_reference()}}), with default values added. Computed \code{width} and
\code{height} values (in pixels) are also included.
}
\description{
You will generally not need to use this function unless you are handling
custom plot output.
Packages needing custom parameters should ask users to place them within
the \code{other.parameters} entry under the package name, e.g.
\if{html}{\out{
}}\preformatted{figures:
other.parameters:
rgl:
fig.asp: 1
}\if{html}{\out{
}}
}
\keyword{internal}
pkgdown/man/test-crayon.Rd 0000644 0001762 0000144 00000001274 14264337707 015256 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test.R
\name{test-crayon}
\alias{test-crayon}
\title{Test case: crayon}
\description{
Test case: crayon
}
\examples{
cat(cli::col_red("This is red"), "\n")
cat(cli::col_blue("This is blue"), "\n")
message(cli::col_green("This is green"))
warning(cli::style_bold("This is bold"))
}
\seealso{
Other tests:
\code{\link{index}},
\code{\link{test-dont}},
\code{\link{test-figures}},
\code{\link{test-links}},
\code{\link{test-lists}},
\code{\link{test-long-lines}},
\code{\link{test-output-styles}},
\code{\link{test-params}},
\code{\link{test-sexpr-title}},
\code{\link{test-verbatim}}
}
\concept{tests}
\keyword{internal}
pkgdown/man/test-links.Rd 0000644 0001762 0000144 00000001316 14343702101 015056 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test.R
\name{test-links}
\alias{test-links}
\title{Test case: links}
\description{
\if{html}{\out{
}}\preformatted{magrittr::subtract(10, 1)
#> [1] 9
}\if{html}{\out{
}}
}
\examples{
magrittr::subtract(10, 1)
library(magrittr, warn.conflicts = FALSE)
subtract(10, 1)
}
\seealso{
Other tests:
\code{\link{index}},
\code{\link{test-crayon}},
\code{\link{test-dont}},
\code{\link{test-figures}},
\code{\link{test-lists}},
\code{\link{test-long-lines}},
\code{\link{test-output-styles}},
\code{\link{test-params}},
\code{\link{test-sexpr-title}},
\code{\link{test-verbatim}}
}
\concept{tests}
\keyword{internal}
pkgdown/man/build_articles.Rd 0000644 0001762 0000144 00000020715 14264307401 015760 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build-articles.R
\name{build_articles}
\alias{build_articles}
\alias{build_article}
\alias{build_articles_index}
\title{Build articles section}
\usage{
build_articles(
pkg = ".",
quiet = TRUE,
lazy = TRUE,
override = list(),
preview = NA
)
build_article(name, pkg = ".", data = list(), lazy = FALSE, quiet = TRUE)
build_articles_index(pkg = ".")
}
\arguments{
\item{pkg}{Path to package.}
\item{quiet}{Set to \code{FALSE} to display output of knitr and
pandoc. This is useful when debugging.}
\item{lazy}{If \code{TRUE}, will only re-build article if input file has been
modified more recently than the output file.}
\item{override}{An optional named list used to temporarily override
values in \verb{_pkgdown.yml}}
\item{preview}{If \code{TRUE}, or \code{is.na(preview) && interactive()}, will preview
freshly generated section in browser.}
\item{name}{Name of article to render. This should be either a path
relative to \verb{vignettes/} without extension, or \code{index} or \code{README}.}
\item{data}{Additional data to pass on to template.}
}
\description{
\code{build_articles()} renders each R Markdown file underneath \verb{vignettes/} and
saves it to \verb{articles/}. There are two exceptions:
\itemize{
\item Files that start with \verb{_} (e.g., \verb{_index.Rmd}) are ignored,
enabling the use of child documents in
\href{https://bookdown.org/yihui/bookdown/}{bookdown}
\item Files in \code{vignettes/tutorials} are handled by \code{\link[=build_tutorials]{build_tutorials()}}
}
Vignettes are rendered using a special document format that reconciles
\code{\link[rmarkdown:html_document]{rmarkdown::html_document()}} with the pkgdown template. This means articles
behave slightly differently to vignettes, particularly with respect to
external files, and custom output formats. See below for more details.
Note that when you run \code{build_articles()} directly (outside of
\code{\link[=build_site]{build_site()}}) vignettes will use the currently installed version of the
package, not the current source version. This makes iteration quicker when
you are primarily working on the text of an article.
}
\section{Index and navbar}{
You can control the articles index and navbar with a \code{articles} field in
your \verb{_pkgdown.yml}. If you use it, pkgdown will check that all articles
are included, and will error if you have missed any.
The \code{articles} field defines a list of sections, each of which
can contain four fields:
\itemize{
\item \code{title} (required): title of section, which appears as a heading on the
articles index.
\item \code{desc} (optional): An optional markdown description displayed underneath
the section title.
\item \code{navbar} (optional): A couple of words used to label this section in
the navbar. If omitted, this section of vignettes will not appear in the
navbar.
\item \code{contents} (required): a list of article names to include in the
section. This can either be names of individual vignettes or a
call to \code{starts_with()}. The name of a vignette includes its
path under \code{vignettes} without extension so that the name of the vignette
found at \code{vignettes/pizza/slice.Rmd} is \code{pizza/slice}.
}
The title and description of individual vignettes displayed on the index
comes from \code{title} and \code{description} fields of the YAML header in the Rmds.
For example, this yaml might be used for some version of dplyr:
\if{html}{\out{
}}\preformatted{articles:
- title: Main verbs
navbar: ~
contents:
- one-table
- two-table
- rowwise
- colwise
- title: Developer
desc: Vignettes aimed at package developers
contents:
- programming
- packages
}\if{html}{\out{
}}
Note the use of the \code{navbar} fields. \verb{navbar: ~} means that the "Main verbs"
will appear in the navbar without a heading; the absence of the \code{navbar}
field in the developer vignettes means that they will only be
accessible via the articles index.
The navbar will include a link to the articles index if one or more
vignettes are not available through the navbar. If some vignettes appear
in the navbar drop-down list and others do not, the list will automatically
include a "More ..." link at the bottom; if no vignettes appear in the
the navbar, it will link directly to the articles index instead of
providing a drop-down.
}
\section{Get started}{
Note that a vignette with the same name as the package (e.g.,
\code{vignettes/pkgdown.Rmd} or \code{vignettes/articles/pkgdown.Rmd}) automatically
becomes a top-level "Get started" link, and will not appear in the articles
drop-down.
(If your package name includes a \code{.}, e.g. \code{pack.down}, use a \code{-} in the
vignette name, e.g. \code{pack-down.Rmd}.)
}
\section{External files}{
pkgdown differs from base R in its handling of external files. When building
vignettes, R assumes that vignettes are self-contained (a reasonable
assumption when most vignettes were PDFs) and only copies files explicitly
listed in \code{.install_extras}. pkgdown takes a different approach based on
\code{\link[rmarkdown:find_external_resources]{rmarkdown::find_external_resources()}}, and it will also copy any images that
you link to. If for some reason the automatic detection doesn't work, you
will need to add a \code{resource_files} field to the yaml metadata, e.g.:
\if{html}{\out{
}}\preformatted{---
title: My Document
resource_files:
- data/mydata.csv
- images/figure.png
---
}\if{html}{\out{
}}
Note that you can not use the \code{fig.path} to change the output directory of
generated figures as its default value is a strong assumption of rmarkdown.
}
\section{Embedding Shiny apps}{
If you would like to embed a Shiny app into an article, the app will have
to be hosted independently, (e.g. \url{https://www.shinyapps.io}). Then, you
can embed the app into your article using an \verb{