pkgdown 2.0.0

  2021/12/03

  devtools, pkgdown

  Hadley Wickham

We’re very chuffed to announce the release of pkgdown 2.0.0. pkgdown is designed to make it quick and easy to build a website for your package. Install it with:

install.packages("pkgdown")

This is a massive release that brings a major visual refresh and a huge number of improvements. This release would not have been possible without pkgdown’s newest author, Maëlle Salmon, who was the powerhouse behind many of the improvements in this release, particularly the switch to Bootstrap 5, improved customisation, and implementation of local search.

There are way too many changes to describe individually here, so this post will focus on the most important new features:

  • The new template that uses Bootstrap 5.
  • The exciting new ways to customise your site.
  • Some of the biggest changes to code display.
  • A grab bag of other cool features.

See the release notes for a complete list of everything that’s changed.

library(pkgdown)

Bootstrap 5

pkgdown comes with a refreshed template that uses Bootstrap 5, a major update over the previous Bootstrap 3. (Bootstrap is the collection of HTML, CSS, and JS files that give pkgdown sites their basic style). Because this is a major change, you’ll need to opt-in by setting the boostrap version in your _pkgdown.yml:

template:
  bootstrap: 5

The old Bootstrap 3 template is superseded; it will continue to work for some time, but it won’t gain any new features and we encourage you to switch to the new template the next time you’re working on your package.

The new theme includes:

  • A number of minor improvements to accessibility, including a larger font size, greater use of aria attributes, and an accessible syntax highlighting colour scheme, designed by Alison Hill.

  • Support for new features like in-line footnotes and tabsets in articles.

  • Since so many packages have lovely logos, the package logo is now displayed on every page and made even more prominent on the home page.

As an added incentive to upgrade your template to Bootstrap 5, you’ll get site search for “free”: pkgdown now supports searching with no external dependencies and no setup. Learn more in vignette("search").

Customisation

The new template is also much easier to customise. A few of the most important features are noted below to whet your appetite; learn more in vignette("customise").

  • You can now easily change the overall visual appearance by picking a Bootswatch theme:

    template:
  bootstrap: 5
  bootswatch: cyborg

    Or by selectively overriding the “ bslib” variables used to generate the CSS:

    template:
  bootstrap: 5
  bslib:
    bg: "#202123"
    fg: "#B8BCC2"
    primary: "#306cc9"
    base_font: {google: "Roboto"}

    You can also choose a different syntax highlighting theme:

    template:
  bootstrap: 5
  theme: arrow-dark

    If any of these options sound intriguing, read vignette("customise") to get the full details!

  • You can now translate the English text that pkgdown contributes to each page. This means that if you’ve written your package documentation in another language, you can ensure that language is also used on every part of the page. Activate the translations by setting the lang field in _pkgdown.yaml, e.g.:

    lang: fr

    pkgdown includes translations for Spanish (es), German (de), French (fr), Portuguese (pt), Turkish (tr) and Chinese (zh_CN). A big thanks to my colleagues who provided the initial translations, and to @dieghernan, @rivaquiroga, @jplecavalier who supplied additional improvements. If you’re interested in adding translations for your language please file an issue and we’ll help you get started.

  • You can add arbitrary HTML to every page with the new includes parameter. This makes it easy to add analytics to your site, e.g. to use plausible.io:

    templates:
  includes:
    in_header: |
      <script defer data-domain="{YOUR DOMAIN}" src="https://plausible.io/js/plausible.js"></script>

    Learn more in ?build_site.

  • The author, sidebar, and footer configuration is much more flexible, allowing you to customise individual components while keeping most of the defaults (previously customisation was mostly all or nothing). See ?build_home and ?build_site for details.

Code display

We made a bunch of smaller tweaks to the display of code:

  • Errors, warnings, and messages are styled minimally to make it easier for package authors to use their own colours and styles.

  • Articles now include colours and font formatting applied by the cli or crayon packages.

  • Long lines in code output are now wrapped, not scrolled. This better matches rmarkdown::html_document() and what you see in the console.

  • You can globally set the width of code output (in reference and articles) with:

    code:
  width: 50

  • The copy button now automatically omits output lines (e.g. #>).

Other new features

  • If you need to move pages, you can provide redirects:

    redirects:
  - ["articles/old-vignette-name.html", "articles/new-vignette-name.html"]
  - ["articles/another-old-vignette-name.html", "articles/new-vignette-name.html"]
  - ["articles/yet-another-old-vignette-name.html", "https://pkgdown.r-lib.org/dev"]

    (Old path on the left, new path on the right)

  • You can selectively show HTML only on the devel or release site by adding class pkgdown-devel or pkgdown-release. This is most easily accessed from .Rmd files where you can use pandoc’s <div> syntax to control where a block of markdown will display. For example, you can use the following markdown in your README to only show GitHub install instructions on the development version of your site:

    ::: {.pkgdown-devel}
You can install the development version of pkgdown from GitHub with:
`remotes::install_github("r-lib/pkgdown")`
:::

  • Support for as_is: true and custom output formats for vignettes/articles has been somewhat improved. Support is fundamentally limited due to the challenges of integrating HTML from output formats that pkgdown doesn’t know about, but it should be a little more reliable and a little better documented.

Acknowledgements

@1beb, @a-beretta, @aaamini, @adamsma, @AdrianAntico, @alanaw1, @aleruete, @amirmasoudabdol, @Anirban166, @apreshill, @arisp99, @atusy, @ayushnoori, @b4D8, @bastistician, @bbolker, @Bisaloo, @c4f3a0ce, @cbailiss, @cboettig, @cderv, @chrarnold, @colearendt, @cpsievert, @crazycapivara, @davidchall, @DavidPatShuiFong, @dcnorris, @dcousin3, @debruine, @dfriend21, @dieghernan, @djnavarro, @dmurdoch, @drwilkins, @earowang, @EmilHvitfeldt, @exploringfinance, @fangzhou-xie, @fenguoerbian, @francojc, @gaborcsardi, @gadenbuie, @GeoBosh, @GitHunter0, @gustavdelius, @hadley, @HenrikBengtsson, @hfrick, @ijlyttle, @IndrajeetPatil, @JakeVestal, @jakob-wirbel, @JamesHWade, @jayhesselberth, @JedGrabman, @jennybc, @jessekps, @jhelvy, @jimhester, @john-harrold, @jonkeane, @jplecavalier, @jrosen48, @jscott6, @kevinushey, @kjhealy, @klmr, @krassowski, @krlmlr, @kuriwaki, @kyleam, @laresbernardo, @lbusett, @lionel-, @maelle, @ManuelHentschel, @MarkEdmondson1234, @matthewstrasiotto, @mattwarkentin, @maxheld83, @mcanouil, @mfherman, @mikeroswell, @mine-cetinkaya-rundel, @mjsteinbaugh, @moutikabdessabour, @mrcaseb, @msberends, @mtkerbeR, @nandp1, @npranav10, @p-carter, @pachadotdev, @paulponcet, @peterblattmann, @renejuan, @rich-iannone, @Rmomal, @Robinlovelace, @royfrancis, @rundel, @salim-b, @samuel-marsh, @samuel-rosa, @sarahemlin, @SchmidtPaul, @statnmap, @stefanoborini, @strengejacke, @topepo, @vandenman, @wlandau, @wolski, @wviechtb, @ycphs, and @yitao-li.

Contents