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.

Getting started

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 _pkgdown.yml:

template:
  bootstrap: 4

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.

Theming

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.

Choosing a Bootswatch theme

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(3) or 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 pkgdown configuration.

template:
  bootstrap: 4
  bootswatch: materia

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:

template:
  params:
    highlightcss: false

You will then have to provide your own CSS rules for syntax highlighting.

bslib variables

Rather than picking an entire theme, you can customise individual theme components using bslib variables:

template:
  bootstrap: 4
  bslib:
    font_scale: 1.2
    base_font:
      google: "Prompt"
    heading_font:
      google: "Muli"
    code_font:
      google: "JetBrains Mono"
    bg: "#202123"
    fg: "#B8BCC2"
    primary: "#EA80FC"
    success: "#4F9B29"
    info: "#28B3ED"
    warning: "#FD7424"
    danger: "#F7367E"

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:

template:
  bootstrap: 4
  bootswatch: materia
  bslib:
    bg: "#202123"
    fg: "#B8BCC2"

More CSS / JS / other assets

If you know CSS or JS, you can customise your site by including pkgdown/extra.css or 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 init_site().

Layout

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 ?build_home.

Templates

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.html is inserted right before closing the head tag.
  • before-body.html is inserted right after opening the body tag.
  • after-body.html is inserted right before closing the body tag.

To add content to these templates:

  • Create a folder pkgdown/templates.
  • Create in-header.html, before-body.html or after-body.html in that folder, depending on your needs. E.g. you could save the lines corresponding to your analytics provider, if not Google Analytics, in pkgdown/templates/in-header.html.
  • Edit and save that file.
  • Re-build your website, inspect it (and its source, if needed).

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

Sharing pkgdown styles: template packages

To share a pkgdown style across several packages, the best workflow is to create… a package! It can contain any of the following:

  • A configuration file in inst/pkgdown/_pkgdown.yml. This can be used to set (e.g.) author definitions, Bootstrap version and variables, the sidebar, footer, navbar, etc. Configuration parameters supplied by a template package have low priority: they will be overridden by a local _pkgdown.yml which is in turn overridden by override parameter of build_site().
  • Templates in inst/pkgdown/templates/ will override the default templates.
  • Assets in inst/pkgdown/assets/ will be copied in to the destination directory.

Once you have created your template package theverybest, you can use it by:

  • Setting it as your sites theme:

    template:
      package: theverybest
  • If you’re building your site using GitHub actions or other similar tool, you’ll also need to installed theverybest. If you’re using remotes or pak to install packages, you can add the following line to your DESCRIPTION:

    Config/Needs/website: theverybest

You then need to ensure the remotes/pak steps you use install packages from this DESCRIPTION field.

The pkgdown website of pkgdown is itself customized as little as possible. To get some sense of how a theming package works you can look at:

But please note that these templates aren’t suitable for use with your own package as they’re all designed to give a common visual identity to a specific family of packages.

Workflow tips

When crafting a new style you will need to re-build your website quite often. How to have a faster workflow?

  • Use a simpler package for previewing your style. This might be over the top for a single package but if you are working on a template package, the template package can contain minimal vignettes, reference pages for testing.
  • Do not rebuild your package every time: e.g. only re-build the home page via build_home() to get a preview of the home sidebar, or of the footer and navbar.
  • If you edit CSS, you can run init_site() to have them copied to your website folder, and then refresh the website in your browser.

Previews on pull requests

Furthermore, it might be useful for you to get a preview of the website in internal pull requests. For that, you could use Netlify and GitHub Actions (or apply a similar logic to your toolset):

  • create a new Netlify website (either from scratch by dragging and dropping a simple index.html, or by creating a site from a GitHub repository and then unlinking that repository); from the site settings get its ID to be saved as NETLIFY_SITE_ID in your repo secrets; from your account developer settings get a token to be saved as NETLIFY_TOKEN in your repo secrets.
  • starting from the standard pkgdown workflow usethis::use_github_action("pkgdown"), add some logic to build the site and deploy it to Netlify for pull requests from inside the repository, not pull requests from forks. Example workflow.

Conclusion

In this vignette we explained how to change the theming and layout of pkgdown websites. Further work to improve user experience is:

  • Working on the article (?build_articles) and reference indexes (?build_reference).
  • Writing a compelling README that explains why your package is so cool/useful/fun.
  • Improving the contents of the individual articles and reference topics 😉.