You can alter the design/styling of your pkgdown website to suit your brand and needs. There are two main techniques:
Theming changes colours, fonts, spacing etc. using a Bootswatch template, Bootstrap variables, Bootstrap rules, or custom CSS.
Layout changes the content (or ordering) of e.g. the navbar, authors page, or
<head> tag, by using pkgdown options or templates.
This vignette begins with a discussion of the most common theming and layout options made available through
_pkgdown.yml. We’ll then discuss how to customise the underlying HTML template files, this is less commonly needed but gives you full control over the appearance of the website. Next, we’ll discuss how to give multiple sites the same style by using a package, and we’ll finish up with some workflow advice.
Most theming features work only with Bootstrap 4, so begin by updating your site to use Bootstrap 4 by adding the following lines to your
Overall, the site should look pretty similar, but you should notice a number of small improvements; most importantly the default font is much bigger, making it considerably easier to read. Upgrading to Bootstrap 4 has a low chance of breaking your site, but if you were managing your own pkgdown templates or using custom CSS, you might need to tweak a few files.
There are three main ways to change the visual style of your site:
With a pre-packaged bootswatch theme.
By customising theme variables via bslib.
With your own CSS and JS.
They can be combined depending on your needs.
The easiest way to change the appearance of your website, or to start changing it, is to pick a complete Bootswatch theme. You can choose any Bootswatch theme that’s compatible with the Bootstrap version you use. Run either
bslib::bootswatch_themes(4) to get a list. If you were using the paper theme, note that it was renamed materia in Bootstrap version 4.
To choose a Bootswatch theme here’s what to write in your
NB: Some Bootswatch templates like lux or pulse won’t work out of the box because of their tall navbar. You’ll need to use custom CSS to add padding to the body.
By default pkgdown uses an accessible colour scheme for code highlighting designed to work well on a light background. If you wish to opt out of this colour scheme to suit a dark Bootswatch theme better, set
highlightcss to false:
You will then have to provide your own CSS rules for syntax highlighting.
Rather than picking an entire theme, you can customise individual theme components using bslib variables:
You can find a full list of variables in
vignette("bs4-variables", package = "bslib").
You can also combine both approaches, starting with a Bootswatch theme then changing the bits you don’t like:
If you know CSS or JS, you can customise your site by including
pkgdown/extra.js. These will be automatically copied the home directory of your website and inserted into the
<head> (after the pkgdown defaults).
You can add arbitrary additional files by putting them in
pkgdown/assets/BS4. The contents will be automatically copied to the root of your website folder by pkgdown by
You can also customise the contents of the navbar, footer, and sidebar that appears on the home page of your site. Furthermore, if you want to tweak which authors of the package appear in the sidebar and footer, also refer to
Other layout changes require tinkering with pkgdown templates (in
inst/templates in pkgdown source). Three pkgdown templates are empty by default, so you can fill them with your own content:
in-header.htmlis inserted right before closing the head tag.
before-body.htmlis inserted right after opening the body tag.
after-body.htmlis inserted right before closing the body tag.
To add content to these templates:
after-body.htmlin that folder, depending on your needs. E.g. you could save the lines corresponding to your analytics provider, if not Google Analytics, in
It is possible to customise other templates but this is recommended for advanced users only because you’ll need to keep it up to date as pkgdown itself changes. If you’ve used
head.html in the past, we now recommend switching to using
in-header.html instead. A limitation to tweaking templates is that your templates can only access data that pkgdown specifically supplies; you can learn more in the documentation and source code of
In this vignette we explained how to change the theming and layout of pkgdown websites. Further work to improve user experience is: