Customize your pkgdown website • pkgdown

library(pkgdown)
library(reactable)
library(dplyr)
library(glue)

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"

The main bslib variables you can use to create a theme are bg, fg, and navbar-bg. Optionally, you can also include primary and secondary. Below is a list of which pkgdown website elements each variable will change:

You may also add more specific variables if you wish to override any of these global theme 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:

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

Navbar colors

You can also customize the color scheme of the navbar by using the type and bg parameters. For example, if your theme is dark, you probably want to use a dark navbar:

navbar:
  type: dark

Alternatively, you could use the bg parameter to make the navbar more visually prominent:

navbar:
  type: dark
  bg: primary

Based on your navbar-bg color and the navbar type, Bootstrap automatically calculates a color for the navbar text elements, including the navigation links, the package name (the “brand”), and active/hover states for each. You can instead use the following bslib variables to control these values, depending on whether you choose a light or dark navbar:

will produce a navbar with a background of the primary color (defined by Bootstrap default, a Bootswatch theme, or bslib variable).

To change the color of the navbar background depending on its type, you can also use the bslib variables navbar-light-bg and navbar-dark-bg.

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.

Navbar

By default, the top navbar will contain links to:

“Get Started”, if you have an article with the same name as the package (e.g., vignettes/pkgdown.Rmd).
The reference index.
Articles (i.e., vignettes, if present).
News (if present).
An icon linking to the source repository.

You can override (and even remove) these defaults with the navbar field. It has two primary components: structure and components. These components interact in a somewhat complicated way, but the complexity allows you to make minor tweaks to part of the navbar while relying on pkgdown to automatically generate the rest.

The structure defines the layout of the navbar, i.e. the order of the components, and whether they’re right aligned or left aligned. You can use this component to change the order of the default components, remove some default components and add your own components.

navbar:
 structure:
   left:  [intro, reference, articles, tutorials, news]
   right: [github]

The components describes the appearance of each element in the navbar. It uses the same syntax as RMarkdown. The following YAML snippet illustrates some of the most important features.

navbar:
 components:
   articles:
    text: Articles
    menu:
    - text: Category A
    - text: Title A1
      href: articles/a1.html
    - text: Title A2
      href: articles/a2.html
    - text: -------
    - text: "Category B"
    - text: Title B1
      menu:
      - text: "Sub-category B11"
        href: articles/b11.html
    twitter:
      icon: "fab fa-twitter fa-lg"
      href: https://twitter.com/hadleywickham
      aria-label: "twitter account"

Components can contain sub-menus with headings (indicated by missing href) and separators (indicated by a bunch of -). You can also use icons from fontawesome. When using icons with no text, for accessibility it’s best practice to include an aria-label for screenreader users.

This yaml would override the default “articles” component, and add a new “twitter” component. Unless you explicitly mention new components in the structure they’ll be added to the far right of the left menu.

You can also customize the color scheme of the navbar by using the type and bg parameters:

navbar:
  type: dark
  bg: primary

will produce a navbar with a dark background of the primary color (defined by Bootstrap default, a Bootswatch theme, or bslib variable cf vignette("customization", package ="pkgdown"))

Footer

By default, the footer is automatically populated with:

The names of the authors authors, on the left.
A reference to pkgdown pkgdown, on the right.

The example below puts the authors information on the right together with a legal disclaimer, and puts pkgdown on the left.

footer:
 left:
   structure: [pkgdown]
 right:
   structure: [authors, legal]
   components:
     legal: Provided without ***any warranty***.

Like the navbar and side, you can control both the structure and the components. Unlike the navbar or sidebar, the components of the footer are just pasted together into a string that converted to HTML and insert in the document.

Sidebar

By default, the sidebar is automatically populated with the following elements (in order): links, license, community, citation, authors, dev. We shall first explain their creation, then how to tweak them.

links: The sidebar links are automatically generated by inspecting the URL and BugReports fields of the DESCRIPTION. If your package is developed on GitHub, you can use usethis::use_github_links() to populate these fields.

You can add additional links with a subsection called links, which should contain a list of text + href elements:
```
home:
  links:
  - text: Link text
    href: https://website.com
  - text: Roadmap
    href: /roadmap.html
```
license: Licensing information if LICENSE/LICENCE or LICENSE.md/LICENCE.md files are present.
community: Community information is linked in the side bar using the .github/CONTRIBUTING.md and .github/CODE_OF_CONDUCT.md files, if present.
citation: Citation information from a inst/CITATION file is linked in the sidebar to the authors page.
authors: Author information from DESCRIPTION, see the dedicated section.
dev: Development status badges found in README.md/index.md. pkgdown identifies badges in three ways:
- Any image-containing links between  and , as e.g. created by usethis::use_readme_md() or usethis::use_readme_rmd(). There should always be an empty line after the  line. If you divide badges into paragraphs, make sure to add an empty line before the  line.
- Any image-containing links within <div id="badges"></div>.
- Within the first paragraph, if it only contains image-containing links.
toc: Not added by default (see below), a table of contents for the README.

You can change the order of sidebar components: links, license, community, citation, authors, dev; you can add a README table of contents toc, you can add custom components. The example below creates a sidebar whose only components will be the authors section, a custom section, a table of contents for the README and a Dev Status section if there are badges. The text will be treated as Markdown.

home:
  sidebar:
    structure: [authors, custom, toc, dev]
    components:
      custom:
        title: Funding
        text: We are *grateful* for funding!

Alternatively, you can provide a ready-made sidebar HTML:

home:
  sidebar:
    html: path-to-sidebar.html

Finally, you can completely remove the sidebar.

home:
  sidebar: FALSE

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:

tidytemplate used for tidyverse and tidymodels packages;
quillt used for R Markdown packages;
rotemplate used for rOpenSci packages.

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 😉.