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 main content of 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.

Extra markdown files in the base directory (e.g. ROADMAP.md) or in .github/ (e.g. CODE_OF_CONDUCT.md) are copied by build_home() to docs/ and converted to HTML.

The home page also features a sidebar with information extracted from the package. You can tweak it via the configuration file, to help make the home page an as informative as possible landing page.

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 chunk with include = FALSE.

```{r chunk-name, include=FALSE}
knitr::opts_chunk$set(
  fig.path = "man/figures/"
)
```

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 of the configuration file called home.

Page title and description

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 on search engines, 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 > i.e. “YAML pipes”; this is a convenient way of writing paragraphs of text.)

README header

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

Other homepage tweaks

See the subsections about the sidebar and authors for more tweaks via the pkgdown configuration file.

By default, the sidebar is automatically populated with the following elements (in order): links, license, community, citation, authors, dev. We shall first explain their creation, then how to tweak them.

links: The sidebar links are automatically generated by inspecting the URL and BugReports fields of the DESCRIPTION. If your package is developed on GitHub, you can use usethis::use_github_links() to populate these fields.

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: https://website.com
  - text: Roadmap
    href: /roadmap.html
```
license: Licensing information if LICENSE/LICENCE or LICENSE.md/LICENCE.md files are present.
community: Community information is linked in the side bar using the .github/CONTRIBUTING.md and .github/CODE_OF_CONDUCT.md files, if present.
citation: Citation information from a inst/CITATION file is linked in the sidebar to the authors page.
authors: Author information from DESCRIPTION, see the dedicated section.
dev: 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(). There should always be an empty line after the  line. If you divide badges into paragraphs, make sure to add an empty line before the  line.
- Any image-containing links within <div id="badges"></div>.
- Within the first paragraph, if it only contains image-containing links.
toc: Not added by default (see below), a table of contents for the README.

You can change the order of sidebar components: links, license, community, citation, authors, dev; you can add a README table of contents toc, you can add custom components. The example below creates a sidebar whose only components will be the authors section, a custom section, a table of contents for the README and a Dev Status section if there are badges. The text will be treated as Markdown.

home:
  sidebar:
    structure: [authors, custom, toc, dev]
    components:
      custom:
        title: Funding
        text: We are *grateful* for funding!

Alternatively, you can provide a ready-made sidebar HTML:

home:
  sidebar:
    html: path-to-sidebar.html

Finally, you can completely remove the sidebar.

home:
  sidebar: FALSE

Authors

By default, pkgdown will display author information in three places:

the sidebar,
the left part side of the footer,
the author page.

This documentation describes how to customise the overall author display. See ?build_home and ?build_footer for details about changing the location of the authors information within the sidebar/footer.

Authors ORCID and bio

Author ORCID identification numbers in the DESCRIPTION are linked 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")
    )
  )

If you want to add more details about authors or their involvement with the package, you can use the comment field, which will be rendered on the authors page.

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

YAML config - authors

You can tweak a few things via the authors YAML field:

display of each author in the footer, sidebar and authors page,
which authors (by role) are displayed in the sidebar and footer,
text before authors in the footer,
text before and after authors in the sidebar,
text before and after authors on the authors page.

You can modify how each author’s name is displayed 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.

authors:
  firstname lastname:
    href: "http://name-website.com"
    html: "<img src='name-picture.png' height=24>"

By default, the “developers” list shown in the sidebar and footer is populated by the maintainer (“cre”), authors (“aut”), and funder (“fnd”) from the DESCRIPTION. You could choose other roles for filtering. With the configuration below:

only the maintainer and funder(s) appear in the footer, after the text “Crafted by”,
all authors and contributors appear in the sidebar,
the authors list on the sidebar is preceded and followed by some text,
the authors list on the authors page is preceded and followed by some text.

authors:
  footer:
    roles: [cre, fnd]
    text: "Crafted by"
  sidebar:
    roles: [aut, ctb]
    before: "So *who* does the work?"
    after: "Thanks all!"
  before: "This package is proudly brought to you by:"
  after: "See the [changelog](news/index.html) for other contributors. :pray:"

If you want to filter authors based on something else than their roles, consider using a custom sidebar/footer component (see ?build_home/?build_site, respectively).