pkgdown 1.5.0

  2020/03/25

  pkgdown, web

  Hadley Wickham

We’re well chuffed to announce that pkgdown 1.5.0 is now available on CRAN. pkgdown is designed to make it quick and easy to build a website for your package. Install it with:

install.packages("pkgdown")

The most important changes are highlighted below and you can see a full list of changes in the changelog.

Articles

For packages with many vignettes/articles, we’ve provided much greater control over the articles index and navbar. There are two major new features in this release:

  • The articles index page now displays article descriptions, taken from YAML metadata in the header of each article. This lets you provide more context for each article.

  • The articles navbar is now controlled by the articles section in _pkgdown.yml. The ordering of the sections, and articles within them, control the order of the articles in the navbar, and you can use the new navbar field to control whether or not each section appears in the navbar.

Learn more about both of these features in ?build_articles.

Thanks to Garrick Aden-Buie, you also get much richer control over Open Graph and Twitter metadata for individual articles. See new vignette("metadata") for details.

Reference index

For packages with many documentation topics, you can add an additional layer of hierarchy to the reference index, using the new subtitle field. To give you some sense for what that might look like, here’s an example for a partial (and imaginary) dplyr reference index:

references:
- title: Data manipulation
- subtitle: One table
- contents:
  - arrange
  - filter
  - mutate
- subtitle: two table
- contents:
  - ends_with("_join")

- title: Datasets
- contents: 
  - has_keyword("datasets")

Tables of contents

Sidebar tables of contents now use bootstrap-toc, which considerably improves navigation for long articles and reference pages.

Other source repositories

You can now control the links to source files (in reference pages and articles) and issues and users (in the NEWS) with new the repo$url config parameter. This makes it easier to use pkgdown with GitHub enterprise, packages in subdirectories, and other source hosts (like bitbucket).

The YAML looks something like this:

repo:
  url:
    home: https://github.com/r-lib/pkgdown/
    source: https://github.com/r-lib/pkgdown/blob/master/
    issue: https://github.com/r-lib/pkgdown/issues/
    user: https://github.com/

The individual components (e.g. path, issue number, username) are pasted on the end of these urls so they should have trailing /s.

pkgdown now detects GitLab urls automatically (since they use the same structure as GitHub), so you don’t need to set these links if you package is hosted on GitLab, and you’ve included a link to your source repo in the URL or BugReports DESCRIPTION fields.

Acknowledgements

A big thank you goes to @jayhesselberth (the co-maintainer of pkgdown), and to to the 61 other people who helped make this release possible: @AshesITR, @baptiste, @Bisaloo, @carloscinelli, @cboettig, @coatless, @coolbutuseless, @DanielEWeeks, @davidchall, @DavorJ, @dimagor, @erikcs, @ferroao, @floriandeboissieu, @flying-sheep, @fmichonneau, @fmmattioni, @gaborcsardi, @genomaths, @gustavdelius, @hadley, @hbaniecki, @ijlyttle, @IndrajeetPatil, @jangorecki, @jayhesselberth, @jeffwong-nflx, @jennybc, @jeroen, @jimhester, @JoshuaSturm, @jranke, @kevinushey, @kevinwang09, @krlmlr, @lbusett, @lcolladotor, @lgatto, @lindeloev, @lionel-, @lorenzwalthert, @m-l-1, @maelle, @mattmalin, @meghapsimatrix, @mikldk, @mllg, @ms609, @nealrichardson, @nschiett, @nteetor, @pat-s, @peterdesmet, @rupertoverall, @schloerke, @slowkow, @t-kalinowski, @wendtke, @ycphs, @yiluheihei, and @yonicd.

Contents