Build reference section
By default, pkgdown will generate an index that lists all functions in
alphabetical order. To override this, provide a reference section in your
_pkgdown.yml as described below.
build_reference( pkg = ".", lazy = TRUE, examples = TRUE, run_dont_run = FALSE, seed = 1014, override = list(), preview = NA, devel = TRUE, document = "DEPRECATED", topics = NULL ) build_reference_index(pkg = ".")
pkg |
Path to package. |
lazy |
If |
examples |
Run examples? |
run_dont_run |
Run examples that are surrounded in \dontrun? |
seed |
Seed used to initialize so that random examples are reproducible. |
override |
An optional named list used to temporarily override
values in |
preview |
If |
devel |
Determines how code is loaded in order to run examples.
If |
document |
Deprecated Use |
topics |
Build only specified topics. If supplied, sets |
To tweak the index page, add a section called reference to _pkgdown.yml.
It can contain three different types of element:
A title (title + desc), which generates an row containing an <h2>
with optional paragraph description.
A subtitle (subtitle + desc), which generates an row containing an
<h3> with optional paragraph description.
A list of topics (contents), which generates one row for each topic,
with a list of aliases for the topic on the left, and the topic title
on the right.
(For historical reasons you can include contents with a title or
subtitle, but this is no longer recommended).
Most packages will only need to use title and contents components.
For example, here's a snippet from the YAML that pkgdown uses to generate
its own reference index:
reference:
- title: Build
desc: Build a complete site or its individual section components.
- contents:
- starts_with("build_")
- title: Templates
- contents:
- template_navbar
- render_pageBigger packages, e.g. ggplot2, may need an additional layer of structure in order to clearly organise large number of functions:
reference:
- title: Layers
- subtitle: Geoms
desc: Geom is short for geometric element
- contents:
- starts_with("geom")
- subtitle: Stats
desc: Statistical transformations transform data before display.
contents:
- starts_with("stat")desc can use markdown, and if you have a long description it's a good
idea to take advantage of the YAML > notation:
desc: > This is a very _long_ and **overly** flowery description of a single simple function. By using `>`, it's easy to write a description that runs over multiple lines.
contents can contain:
Individual function/topic names.
Weirdly named functions with doubled quoting, once for YAML and once for
R, e.g. "`+.gg`".
starts_with("prefix") to select all functions with common prefix.
ends_with("suffix") to select all functions with common suffix.
matches("regexp") for more complex regular expressions.
has_keyword("x") to select all topics with keyword "x";
has_keyword("datasets") selects all data documentation.
has_concept("blah") to select all topics with concept "blah".
If you are using roxygen2, has_concept() also matches family tags, because
roxygen2 converts them to concept tags.
lacks_concepts(c("concept1", "concept2")) to select all topics
without those concepts. This is useful to capture topics not otherwise
captured by has_concepts().
All functions (except for has_keywords()) automatically exclude internal
topics (i.e. those with \keyword{internal}). You can choose to include
with (e.g.) starts_with("build_", internal = TRUE).
Use a leading - to remove topics from a section, e.g. -topic_name,
-starts_with("foo").
pkgdown will check that all non-internal topics are included on the reference index page, and will generate a warning if you have missed any.
You can optionally supply an icon for each help topic. To do so, you'll need
a top-level icons directory. This should contain .png files that are
either 30x30 (for regular display) or 60x60 (if you want retina display).
Icons are matched to topics by aliases.
You can control the default rendering of figures by specifying the figures
field in _pkgdown.yml. The default settings are equivalent to:
figures: dev: ragg::agg_png dpi: 96 dev.args: [] fig.ext: png fig.width: 7.2916667 fig.height: ~ fig.retina: 2 fig.asp: 1.618 bg: NA
Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.