build_home {pkgdown}R Documentation

Build home section

Description

build_home() function generates pages at the top-level of the site including:

build_home_index() rebuilds just the index page; it's useful for rapidly iterating when experimenting with site styles.

Usage

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

build_home_index(pkg = ".", override = list(), 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}`r ''`
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 - 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.)

Dev badges

pkgdown identifies badges in three ways:

Identified badges are removed from the main content. They are shown or not in the sidebar depending on the development mode and sidebar customization, see the sidebar section.

Authors

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

This documentation describes how to customise the overall author display. See ?build_home and ?build_site for details about changing the location of the authors information within the home sidebar and the site 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")
    )
  )

Additional control via YAML

You can control additinal aspects of the authors display via the authors YAML field:

You can modify how each author's name is displayed by adding a subsection for authors. Each entry in authors should be named the author's name (matching DESCRIPTION) and can contain href and/or html fields: 

authors:
  firstname lastname:
    href: "http://name-website.com"
    html: "<img src='https://website.com/name-picture.png' width=72 alt=''>"

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: 

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).

Sidebar

You can customise the homepage sidebar with the home.sidebar field. It's made up of two pieces: structure, which defines the overall layout, and 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: 

home:
  sidebar:
    structure: [links, license, community, citation, authors, dev]

These are drawn from seven built-in components:

You can also add your own components, where text is markdown text: 

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

Or completely remove it: 

home:
  sidebar: FALSE

See Also

Other site components: build_articles(), build_news(), build_reference(), build_tutorials()

[Package pkgdown version 2.1.0 Index]