pkgdown 2.1.0

  2024/07/08

  devtools, pkgdown

  Hadley Wickham

We’re delighted to announce the release of pkgdown 2.1.0. pkgdown is designed to make it quick and easy to build a beautiful and accessible website for your package.

You can install it from CRAN with:

install.packages("pkgdown")

This is a massive release with a bunch of new features. I’ll highlight the most important here, but as always, I highlight recommend skimming the release notes for other smaller improvements and bug fixes.

First, and most importantly, please join me in welcoming two new authors to pkgdown: Olivier Roy and Salim Brüggemann. They have both contributed many improvements to the package and I’m very happy to officially have them aboard as package authors.

library(pkgdown)

Lifecycle changes

Let’s get started with the important stuff, the lifecycle updates. Most important we’ve decided to deprecate support for Bootstrap 3, which was superseded in December 2021. We’re starting to more directly encourage folks to move away from it as maintaining two separate sets of site templates is a time sink. If you’re still using BS3, now’s the time to upgrade.

There are three other changes that are less likely to affect folks:

Major new features

pkgdown 2.1.0 has two major new features: support for Quarto vignettes and a new light switch that toggles between light and dark modes.

Quarto support

build_article()/ build_articles() now support articles and vignettes written with Quarto. To use it, make sure you have the the latest version of Quarto, 1.5, which was released last week. By and large you should be able to just write in Quarto and things will just work, but you will need to make a small change to your GitHub action. Learn more at vignette("quarto").

Combining the individual quarto and pkgdown templating systems is a delicate art, so while I’ve done my best to make it work, there may be some rough edges. Check out the current known limitations in vignette("quarto"), and please file an issue if you encounter a quarto feature that doesn’t work quite right.

Light switch

pkgdown sites can now provide a “light switch” that allows the reader to switch between light and dark modes (based on work in bslib by @gadenbuie). You can try it out on https://pkgdown.r-lib.org: the light switch appears at the far right at the navbar and remembers the users choice between visits to your site.

(Note that the light switch works differently to quarto dark mode. In quarto, you can provide two completely different themes for light and dark mode. In pkgdown, dark mode is a relatively thin overlay that based on your light theme colours.)

For now, you’ll need to opt-in to the light-switch by adding the following to your _pkgdown.yml:

template
  light-switch: true

In the future we hope to turn it on automatically.

You can learn more about customising the light switch in vignette("customise"): you can choose to select your own syntax highlighting scheme for dark mode, override dark-specific BS lib variables, and move its location in the navbar.

User experience

We’ve made a bunch of small changes to enhance the user experience of pkgdown sites:

  • We’ve continued in our efforts to make pkgdown sites as accessible as possible by now warning if you’ve forgotten to add alt text to images (including plots) in your articles. We’ve also added a new vignette("accessibility") which describes additional manual tasks you can perform to make your site as accessible as possible.

  • build_reference() adds anchors to arguments making it possible to link directly to an argument. This is very useful when you’re trying to direct folks to the documentation for a specific argument, e.g. https://pkgdown.r-lib.org/reference/build_site.html#arg-devel.

  • build_reference_index() now displays function lifecycle badges next to the function name. If you want to gather together (e.g.) all the deprecated function in one spot in the reference index, you can use the new topic selector has_lifecycle("deprecated").

  • The new template.math-rendering option allows you to control how math is rendered on your site. The default uses mathml which is zero dependency but has the lowest fidelity. If you use a lot of math on your site, you can switch back to the previous method with mathjax, or try out katex, a faster alternative.

  • pkgdown sites no longer depend on external content distribution networks (CDN) for common javascript, CSS, and font files. CDNs no longer provide any performance advantages and make deployment harder inside certain locked-down corporate environments.

  • pkgdown includes translations for more terms including “Abstract” and “Search site”. A big thanks to @jplecavalier, @dieghernan, @krlmlr, @LDalby, @rich-iannone, @jmaspons, and @mine-cetinkaya-rundel for providing updated translations in French, Spanish, Portugese, Germna, Catalan, and Turkish!

    I’ve also written vignette("translations"), a brief vignette that discusses how translation works for non-English sites, and includes how you can create translations for new languages. (This is a great way to contribute to pkgdown if you are multi-lingual!)

Developer experience

We’ve also made a bunch of minor improvements to make improve the package developer experience:

  • YAML validation has been substantially improved so you should get much clearer errors if you have made a mistake in your _pkgdown.yml. Please file an issue if you find a case where the error message is not helpful.

  • The build_*() functions (apart from build_site()) no longer automatically preview in interactive sessions since they all emit clickable links to any files that have changed. You can continue to use preview_site() to open the site in your browser.

  • The build_*() functions now work better if you’re previewing just part of a site and haven’t built the whole thing. It should no longer be necessary to run init_site() in most cases, and you shouldn’t be able to get into a state where you’re told to run init_site() and then it doesn’t work.

  • We give more and clearer details of the site building process including reporting on exactly what is generated by bslib, what is copied from templates, and what redirects are generated.

Acknowledgements

A big thanks to all 212 folks who contributed to this release! @Adafede, @AEBilgrau, @albertocasagrande, @alex-d13, @AliSajid, @arkadiuszbeer, @ArneBab, @asadow, @ateucher, @avhz, @banfai, @barcaroli, @BartJanvanRossum, @bastistician, @ben18785, @bijoychandraAU, @Bisaloo, @bkmgit, @bnprks, @brycefrank, @bschilder, @bundfussr, @cararthompson, @Carol-seven, @cbailiss, @cboettig, @cderv, @chlebowa, @chuxinyuan, @cromanpa94, @cthombor, @d-morrison, @DanChaltiel, @DarioS, @davidchall, @DavisVaughan, @dbosak01, @dchiu911, @ddsjoberg, @DeepanshKhurana, @dhersz, @dieghernan, @djhocking, @dkarletsos, @dmurdoch, @dshemetov, @dsweber2, @dvg-p4, @DyfanJones, @ecmerkle, @eddelbuettel, @eeholmes, @eitsupi, @eliocamp, @elong0527, @EmilHvitfeldt, @erikarasnick, @esimms999, @espinielli, @etiennebacher, @ewenharrison, @filipsch, @FlukeAndFeather, @francoisluc, @friendly, @fweber144, @gaborcsardi, @gadenbuie, @galachad, @gangstR, @gavinsimpson, @GeoBosh, @GFabien, @ggcostoya, @ghost, @givison, @gladkia, @glin, @gmbecker, @gravesti, @GregorDeCillia, @gregorypenn, @gsmolinski, @gsrohde, @gungorMetehan, @hadley, @harshkrishna17, @HenrikBengtsson, @hfrick, @hrecht, @hsloot, @idavydov, @idmn, @igordot, @IndrajeetPatil, @jabenninghoff, @jack-davison, @jangorecki, @jayhesselberth, @jennybc, @jeroen, @JerryWho, @jhelvy, @jmaspons, @john-harrold, @john-ioannides, @jonasmuench, @jonnybaik, @josherrickson, @joshualerickson, @JosiahParry, @jplecavalier, @JSchoenbachler, @juliasilge, @jwimberl, @kalaschnik, @kevinushey, @klmr, @krlmlr, @LDalby, @ldecicco-USGS, @lhdjung, @LiNk-NY, @lionel-, @Liripo, @lorenzwalthert, @lschneiderbauer, @mabesa, @maelle, @maRce10, @margotbligh, @marine-ecologist, @markfairbanks, @martinlaw, @matt-dray, @mattfidler, @matthewjnield, @MattPM, @mccarthy-m-g, @MEO265, @merliseclyde, @MichaelChirico, @mikeblazanin, @mikeroswell, @mine-cetinkaya-rundel, @MLopez-Ibanez, @Moohan, @mpadge, @mrcaseb, @mrchypark, @ms609, @msberends, @musvaage, @nanxstats, @nathaneastwood, @netique, @nicholascarey, @nicolerg, @olivroy, @pearsonca, @peterdesmet, @phauchamps, @przmv, @quantsch, @ramiromagno, @rcannood, @rempsyc, @rgaiacs, @rich-iannone, @rickhelmus, @rmflight, @robmoss, @royfrancis, @rsangole, @ryantibs, @salim-b, @samuel-marsh, @SebKrantz, @SESjo, @sgvignali, @spsanderson, @srfall, @stefanoborini, @stephenashton-dhsc, @strengejacke, @swsoyee, @t-kalinowski, @talgalili, @tanho63, @tedmoorman, @telphick, @TFKentUSDA, @ThierryO, @thisisnic, @thomasp85, @tomsing1, @tony-aw, @trevorld, @tylerlittlefield, @uriahf, @urswilke, @ValValetl, @venpopov, @vincentvanhees, @wangq13, @willgearty, @wviechtb, @xuyiqing, @yjunechoe, @ynsec37, @zeehio, and @zkamvar.

Contents