Customise your site

Light switch

You can provide a “light switch” to allow your users to switch between dark and light themes by setting the light-switch template option to true:

template:
  light-switch: true

This will add a lightswitch component to the navbar, which by default appears at the far right. This allows the user to select light mode, dark mode, or auto mode (which follows the system setting). The modes are applied using Bootstrap 5.3’s colours modes so are not separate themes, but a thin layer of colour customisation applied via CSS.

Bootswatch themes

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

template:
  bootstrap: 5
  bootswatch: materia

(Themes are unlikely to work with the light switch, but you can try it and see.)

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

Bootswatch templates with tall navbars (e.g. lux, pulse) also require that you set the pkgdown-nav-height bslib variable. Because Bootswatch themes are provided by the bslib R package, you can also nest the bootswatch field under the bslib field.

template:
  bootstrap: 5
  bslib:
    bootswatch: lux
    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:

• bg (background) determines the page background.
• fg (foreground) determines the text colour. bg and fg are mixed to yield gray-100, gray-200, …, grey-900, which are used to style other elements to match the overall colour scheme.
• primary sets the link colour and the (translucent) hover colour in the navbar and sidebar.

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 and 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 the bslib docs.

If you’re using the light switch, many colours are available for customisation specifically for the dark theme.

Theming with bslib is powered by bslib::bs_theme() and the bslib field is a direct translation of the arguments to that function. As a result, you can fully specify a bslib theme using the template.bslib field, making it easy to share YAML with the output.html_document.theme field of an R Markdown document.

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

While iterating on colours and other variables you only need to rerun init_site() and refresh your browser to see the changes.

Fonts

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 with the following syntax:

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

If you want to use a non-Google font, you’ll need to do a bit more work. There are two steps: you need to first configure the font with CSS and then use it in your _pkgdown.yml. There are two ways you might get the CSS:

• As a block of CSS which you should put in pkgdown/extra.scss or pkgdown/extra.css. The CSS will look something like this:

  @font-face {
    font-family: "proxima-nova";
    src: 
      local("Proxima Nova Regular"), 
      local("ProximaNova-Regular"),
      url("https://example.com/ProximaNova-Regular.eot?#iefix") format("embedded-opentype"),
      url("https://example.com/fonts/proxima/ProximaNova-Regular.woff2") format("woff2"),
      url("https://example.com/fonts/proxima/ProximaNova-Regular.woff") format("woff"),
      url("https://example.com/fonts/proxima/ProximaNova-Regular.ttf") format("truetype");
    font-weight: normal;
    font-style: normal;
    font-display: fallback;
  }

• As a link to a style file, which you’ll need to add to the <head> using this syntax:

  template:
  includes:
    in_header: <link rel="stylesheet" type="text/css" href="https://..." />

Then in _pkgdown.yml you can use the name of the font you just specified:

template:
  bslib:
    base_font: proxima-nova

Depending on where the font is from (and if you purchased it), you may need to take additional steps to ensure that it can only be used from your site, and/or make sure that it can still be used when you’re previewing locally. If you’re having problems getting a custom font to work, looking for errors in the browser developer console is a good place to start.

When iterating on fonts, you’ll need to run build_home_index(); init_site() then refresh your browser to see the update.

Syntax highlighting

The colours used for syntax highlighting in code blocks are controlled by the theme setting:

template:
  bootstrap: 5
  theme: breeze-light

You can choose from any of the following options: a11y-dark, a11y-light, arrow-dark, arrow-light, atom-one-dark, atom-one-light, ayu-dark, ayu-light, ayu-mirage, breeze-dark, breeze-light, breezedark, dracula, espresso, github-dark, github-light, gruvbox-dark, gruvbox-light, haddock, kate, monochrome-dark, monochrome-light, monochrome, monokai, nord, oblivion, printing, pygments, radical, solarized-dark, solarized-light, solarized, tango, vim-dark, zenburn.

Bootswatch themes with a dark background (e.g. cyborg, darkly, solar) will need a dark syntax highlighting theme, e.g. arrow-dark:

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

If you’re using the light switch, you will want to provide a theme and a theme-dark:

template:
  light-switch: true
  theme: gruvbox-light
  theme-dark: gruvbox-dark

The foreground and background colours used for inline code are controlled by code-color and code-bg bslib variables. If you want inline code to match code blocks, you’ll need to override the variables yourself, e.g.:

template: 
  bootstrap: 5
  theme: arrow-dark  
  bslib:
    code-bg: "#2b2b2b"

Math rendering

By default, pkgdown will render math using mathml. mathml is the official standard for rendering math on the web, and requires no additional javascript or css dependencies. However, browser support for complex math is not always that good, so if you are including complex equations in your documentation, you may want to switch to either katex or mathjax by using the template.math-rendering field:

template:
  math-rendering: katex

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 Bootswatch preview. Similarly, you don’t usually need to set type because bootstrap will guess it for you. If the guess is wrong, you can 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.

Navbar

You can customise the navigation bar that appears at the top of the page with the navbar field. It’s made up of two pieces: structure, which defines the overall layout, and components, which defines what each piece looks like. This organisation makes it easy to mix and match pkgdown defaults with your own customisations.

This is the default structure:

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

It makes use of the the following built-in components:

• intro: “Get Started”, which links to a vignette or article with the same name as the package¹.
• reference: if there are any .Rd files.
• articles: if there are any vignettes or articles.
• tutorials: if there any tutorials.
• news: if NEWS.md exists.
• search: the search box (see ?build_search for more details).
• github: a link to the source repository (with an icon), if it can be automatically determined from the DESCRIPTION.
• lightswitch; a “light switch” to select light mode, dark mode, or auto mode.

Note that customising navbar like this comes with a downside: if pkgdown later changes the defaults, you’ll have to update your _pkgdown.yml.

You can use the structure field to reorganise the navbar without changing the default contents:

navbar:
  structure:
    left:  [search]
    right: [reference, articles]

You can use components to override the default content. For example, this yaml provides a custom articles menu:

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: Article B1
      href: articles/b1.html

Components uses the same syntax as RMarkdown menus. The elements of menu can be:

• Linked text (text, href, and an optional target).

• A linked icon (icon, aria-label, href, and an optional target). You can find a list of available icons at fontawesome. Provide a text description of the icon in the aria-label field for screenreader users.

• A heading (just text).

• A separator (text: ——–).

To add a new component to the navbar, you need to modify both structure and components. For example, the following yaml adds a new “twitter” component that appears to the left of the github icon.

navbar:
  structure:
    right: [search, twitter, github, lightswitch]
  components:
    twitter:
      icon: fa-twitter
      href: http://twitter.com/hadleywickham
      aria-label: Twitter

Finally, you can add arbitrary HTML to three locations in the navbar:

template:
  includes:
    before_title: <!-- inserted before the package title in the header ->
    before_navbar: <!-- inserted before the navbar links -->
    after_navbar: <!-- inserted after the navbar links -->

These inclusions will appear on all screen sizes, and will not be collapsed into the the navbar drop down.

You can also customise the colour scheme of the navbar by using the type and bg parameters. See above for details.

Footer

You can customise the footer with the footer field. It’s made up of two pieces: structure, which defines the overall layout, and components, which defines what each piece looks like. This organisation makes it easy to mix and match the pkgdown defaults with your own customisations.

This is the default structure:

footer:
  structure: 
    left: developed_by
    right: built_with

Which uses two of the three built-in components:

• developed_by: a sentence describing the main authors of the package. (See ?build_home if you want to tweak which authors appear in the footer.)
• built_with: a sentence advertising pkgdown.
• package: the name of the package.

You can override these defaults with the footer field. The example below puts the author’s information on the right along with a legal disclaimer, and puts the pkgdown link on the left.

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

Each side is pasted into a single string (separated by " ") and then converted from markdown to HTML.

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.