Build home section

This function generates the home page, converts .md files found in the package root (and in .github/), and builds an authors page from DESCRIPTION and inst/CITATION (if present).

build_home(pkg = ".", override = list(), preview = NA, quiet = TRUE)

Arguments

pkg	Path to package.
override	An optional named list used to temporarily override values in `_pkgdown.yml`
preview	If `TRUE`, or `is.na(preview) && interactive()`, will preview freshly generated section in browser.
quiet	Set to `FALSE` to display output of knitr and pandoc. This is useful when debugging.

Home page

The home page (index.html) is generated from _pkgdown/index.md, index.md, or README.md, in that order. Most packages will use README.md because that's also displayed by GitHub and CRAN. Use index.md if you want your package website to look different to your README, and use _pkgdown/index.md if you don't want that file to live in your package root directory.

If you use index.Rmd or README.Rmd it's your responsibility to knit the document to create the corresponding .md. pkgdown does not do this for you because it only touches files in the doc/ directory.

The sidebar is automatically populated with:

Development status badges found in README.md/index.md. pkgdown identifies badges in three ways:
- Any image-containing links between  and , as e.g. created by usethis::use_readme_md() or usethis::use_readme_rmd().
- Any image-containing links within <div id="badges"></div>.
- Within the first paragraph, if it only contains image-containing links.
A link for bug reports is added if the BugReports field in DESCRIPTION contains a link. You can use usethis::use_github_links() to populate this field.
Licensing information if LICENSE/LICENCE or LICENSE.md/LICENCE.md files are present.
Community information is linked in the side bar using the .github/CONTRIBUTING.md and .github/CODE_OF_CONDUCT.md files, if present.
Extra markdown files in the base directory or in .github/ are copied to docs/ and converted to HTML.
Citation information from a inst/CITATION file is linked in the side bar to the authors page.

Author ORCID identification numbers in the DESCRIPTION are linked under "Developers" using the ORCID logo:

Authors@R: c(
    person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"),
      comment = c(ORCID = "0000-0003-4757-117X")
    ),
    person("Jay", "Hesselberth", role = "aut",
      comment = c(ORCID = "0000-0002-6299-179X")
    )
  )

Images and figures

If you want to include images in your README.md, they must be stored somewhere in the package so that they can be displayed on the CRAN website. The best place to put them is man/figures. If you are generating figures with R Markdown, make sure you set up fig.path as followed:

knitr::opts_chunk$set(
  fig.path = "man/figures/"
)

This should usually go in a block with include = FALSE.

Package logo

If you have a package logo, you can include it at the top of your README in a level-one heading:

# pkgdown <img src="man/figures/logo.png" align="right" />

init_site() will also automatically create a favicon set from your package logo.

YAML config - home

To tweak the home page, you need a section called home.

By default, the page title and description are extracted automatically from the Title and Description fields DESCRIPTION (stripping single quotes off quoted words). CRAN ensures that these fields don't contain phrases like "R package" because that's obvious on CRAN. To make your package more findable with google, it's good practice to override the title and description, thinking about what people might search for:

home:
  title: An R package for pool-noodle discovery
  description: >
    Do you love R? Do you love pool-noodles? If so, you might enjoy
    using this package to automatically discover and add pool-noodles
    to your growing collection.

(Note the use of YAML's >; this is a convenient way of writing paragraphs of text.)

The sidebar links are automatically generated by inspecting the URL and BugReports fields of the DESCRIPTION. You can add additional links with a subsection called links, which should contain a list of text + href elements:

home:
  links:
  - text: Link text
    href: http://website.com

READMEs usually start with an <h1> containing the package name. If that feels duplicative with the package name in the navbar you can remove it with strip_header: true:

home:
  strip_header: true

YAML config - authors

The "developers" list is populated by the maintainer ("cre"), authors ("aut"), and funder ("fnd") from the DESCRIPTION. You can modify their display on the home page by adding a subsection for authors. Each entry in authors should be named with the author's name (matching DESCRIPTION) and can contain href and/or html fields:

If href is provided, the author's name will be linked to this url.
If html is provided, it will be shown instead of the author's name. This is particularly useful if you want to display the logo of a corporate sponsor.