Customise your site

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

This vignette teaches you how to customise the style/design of your pkgdown site. We'll start by discussing two techniques that only require tweaks to your _pkgdown.yaml: theming (colours and fonts) and layout (content of the navbar, sidebar, footer, ...). We'll then discuss how to add additional HTML and other files. Next, we'll discuss how to give multiple sites the same style using a package, then finish up with some workflow advice.

library(pkgdown)

Getting started

Most theming features work only with Bootstrap 5, so first update your site by adding the following lines to your _pkgdown.yml:

template:
  bootstrap: 5

Overall, the site should look pretty similar, but you will notice a number of small improvements. Most importantly, the default font is much bigger, making it considerably easier to read. Upgrading to Bootstrap 5 has a low chance of breaking your site unless you were using your own pkgdown templates or custom CSS.

Theming

There are two ways to change the visual style of your site from _pkgdown.yaml: using a pre-packaged bootswatch theme or customising theme variables with bslib. The following sections show you how.

Bootswatch themes

The easiest way to change the entire appearance of your website is to use a Bootswatch theme:

template:
  bootstrap: 5
  bootswatch: materia

Changing the bootswatch theme affects both the HTML (via the navbar, more on that below) and the CSS, so you'll need to re-build your complete site with build_site() to fully appreciate the changes. While you're experimenting, you can speed things up by just rebuilding the home page and the CSS by running build_home_index(); init_site() (and then refreshing the browser).

Theme with a dark background (e.g. cyborg, darkly, solar) will also need a different syntax highlight theme. The dark equivalent of the default light colour scheme is called arrow-dark:

template:
  bootstrap: 5
  bootswatch: cyborg
  theme: arrow-dark

Other themes you can use are r paste0(pkgdown:::highlight_styles(), collapse = ", ").

Bootswatch templates with tall navbars (e.g. lux, pulse) also require that you set the pkgdown-nav-height bslib variable:

template:
  bootstrap: 5
  bootswatch: lux
  bslib:
    pkgdown-nav-height: 100px

You can find the correct height by running $(".navbar").outerHeight() in the javascript console.

bslib variables

Instead of picking a complete theme, you can tweak fonts and colours individually using bslib variables. bslib is an R package that wraps sass, the tool that Boostrap uses to produce CSS from a special language called scss. The primary advantage of scss over CSS is that it's more programmable, so you can have a few key bslib variables that affect appearance of many HTML elements.

There are three key variables that affect the colour:

template:
  bootstrap: 5
  bslib:
    bg: "#202123"
    fg: "#B8BCC2"
    primary: "#306cc9"

You can customise other components by setting more specific bslib variables, taking advantage of inheritance where possible. For example, table-border-color defaults to border-color which defaults to gray-300. If you want to change the colour of all borders, you can set border-color; if you just want to change the colour of table borders, you can set table-border-color. You can find a full list of variables in vignette("bs5-variables", package = "bslib").

You can also override the default fonts used for the majority of the text (base_font), for headings (heading_font) and for code (code_font). The easiest way is to supply the name of a Google font:

template:
  bootstrap: 5
  bslib:
    base_font: {google: "Roboto"}
    heading_font: {google: "Roboto Slab"}
    code_font: {google: "JetBrains Mono"}

While iterating on colours and other variables you only need to rerun init_site() and refresh your browser; when iterating on fonts, you'll need to run build_home_index(); init_site().

Navbar style

The primary navbar colours are determined by HTML classes, not CSS, and can be customized using the navbar fields bg and type which control the background and foreground colours respectively. Typically bg will be one of light, dark, or primary:

navbar:
  bg: primary

You generally don't need to set bg if you use a bootswatch theme, as pkgdown will pick the bg used on the Bootstwatch preview. Similarly, you don't usually need to set type because bootstrap will guess it for you. If it guesses wrong, override with type: light or type: dark depending on whether the background colour is light (so you need dark text) or type: dark if the background is dark (so you need light text). Unfortunately, these are defined relative to the page background, so if you have a dark site you'll need to flip light and dark (a little experimentation should quickly determine what looks best).

Because the navbar is styled with HTML, you'll need to build_home_index(); init_site() to see the effect of changing this parameter.

Layout {#layout}

You can customise the contents of the navbar, footer, and home page sidebar using the navbar, footer, and sidebar fields. They all use a similar structure that separately defines the overall structure and the individual components.

Navbar


Footer


Sidebar


Additional HTML and files

If you need to include additional HTML, you can add it in the following locations:

template:
  includes:
    in_header: <!-- inserted at the end of the head -->
    before_body: <!-- inserted at the beginging of the body -->
    after_body: <!-- inserted at the end of the body -->
    before_title: <!-- inserted before the package title in the header ->
    before_navbar: <!-- inserted before the navbar links -->
    after_navbar: <!-- inserted after the navbar links -->

You can include additional files by putting them in the right place:

Use init_site() to update your rendered website after making changes to these files.

Template packages {#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:

Any configuration/files supplied will override the pkgdown defaults, but will be overridden by site specific settings.

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

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.

Porting a template package

If you are updating a template package that works with pkgdown 1.0.0, create directories inst/pkgdown/BS5/templates and inst/pkgdown/BS5/assets (if you don't have any templates/assets make sure to a add dummy file to ensure that git tracks them). The templates and assets directories directly under inst/pkgdown will be used by pkgdown 1.0.0 and by pkgdown 2.0.0 if boostrap: 3. The directories under inst/pkgdown/BS5/ will be used for pkgdown 2.0.0 with boostrap: 5. This lets your package support both versions of bootstrap and pkgdown.

PR previews

Lastly, 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):

Conclusion

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



Try the pkgdown package in your browser

Any scripts or data that you put into this service are public.

pkgdown documentation built on April 24, 2022, 5:05 p.m.