--- title: "Customise your site" output: rmarkdown::html_vignette description: > Learn how to change the look and feel of your pkgdown site. vignette: > %\VignetteIndexEntry{Customise your site} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} 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.yml`: 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. ```{r setup} 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`: ``` yaml 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](#template-packages) or custom CSS. ## Theming There are two ways to change the visual style of your site from `_pkgdown.yml`: using a pre-packaged bootswatch theme or customising theme variables with [bslib](https://rstudio.github.io/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](https://bootswatch.com): ``` yaml 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). 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](https://rstudio.github.io/bslib/) R package, you can also nest the `bootswatch` field under the `bslib` field. ``` yaml template: bootstrap: 5 bslib: bootswatch: lux pkgdown-nav-height: 100px ``` You can find the correct height by running `$(".navbar").outerHeight()` in the [javascript console](https://firefox-source-docs.mozilla.org/devtools-user/web_console/index.html). ### bslib variables Instead of picking a complete theme, you can tweak fonts and colours individually using bslib variables. [bslib](https://rstudio.github.io/bslib/) is an R package that wraps sass, the tool that Boostrap uses to produce CSS from a special language called [scss](https://sass-lang.com). 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. ``` yaml 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](https://fonts.google.com): ``` yaml 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()`. 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](https://rstudio.github.io/bslib/articles/theming/index.html). ``` yaml template: bslib: version: 5 bootswatch: lux base_font: {google: "Roboto"} heading_font: {google: "Roboto Slab"} code_font: {google: "JetBrains Mono"} ``` ### Syntax highlighting The colours used for syntax highlighting in code blocks are controlled by the `theme` setting: ``` yaml template: bootstrap: 5 theme: breeze-light ``` You can choose from any of the following options: `r paste0(pkgdown:::highlight_styles(), collapse = ", ")`. Bootswatch themes with a dark background (e.g. cyborg, darkly, solar) will need a dark syntax highlighting `theme`, e.g. `arrow-dark`: ``` yaml template: bootstrap: 5 bootswatch: cyborg theme: arrow-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.: ``` yaml template: bootstrap: 5 theme: arrow-dark bslib: code-bg: "#2b2b2b" ``` ### 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`: ``` yaml 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](https://bootswatch.com/). 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 {#navbar-heading} ```{r child="../man/rmd-fragments/navbar-configuration.Rmd"} ``` ### Footer ```{r child="../man/rmd-fragments/footer-configuration.Rmd"} ``` ### Sidebar ```{r child = "../man/rmd-fragments/sidebar-configuration.Rmd"} ``` ## Additional HTML and files If you need to include additional HTML, you can add it in the following locations: ``` yaml template: includes: in_header: before_body: after_body: before_title: after_navbar: ``` You can include additional files by putting them in the right place: - `pkgdown/extra.css` and `pkgdown/extra.js` will be copied in to rendered site and linked from `` (after the pkgdown defaults). - `pkgdown/extra.scss` will be added to the scss ruleset used to generate the site CSS. - Any files in `pkgdown/assets` will be copied to the website root directory. - For expert users: template files in `pkgdown/templates` will override layout templates provided by pkgdown or [template packages](#template-packages). 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: - 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. - Templates in `inst/pkgdown/templates/` will override the default templates. - Assets in `inst/pkgdown/assets/` will be copied in to the destination directory. (Note these files are only copied; you'll need to reference them in your stylesheet or elsewhere in order for them to be actually used.) - `inst/pkgdown/extra.scss` will be added to the bslib ruleset. (Note that `extra.css` is not supported in templates.) The pkgdown defaults will be overriden by these template files, which are in turn overridden by package specific settings. Once you have created your template package `theverybest`, you need to set it as your site's theme: ``` yaml template: package: theverybest ``` You then also need to make sure it's available when your site is build. Typically, you won't want to publish this package to CRAN, but you will want to publish to GitHub. Once you've done that, and assuming you're using the [usethis workflow](https://usethis.r-lib.org/reference/use_pkgdown.html), add the following line to your `DESCRIPTION`: ```yaml Config/Needs/website: myorg/theverybest ``` This will ensure that the GitHub action will automatically install it from GitHub when building your pkgdown site. To get some sense of how a theming package works, you can look at: - [tidytemplate](https://tidytemplate.tidyverse.org/) used for tidyverse and tidymodels packages; - [quillt](https://pkgs.rstudio.com/quillt) used for R Markdown packages; - [rotemplate](https://github.com/ropensci-org/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. ### 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): - 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_AUTH_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](https://github.com/r-lib/pkgdown/blob/master/.github/workflows/pkgdown.yaml). ## Conclusion In this vignette we explained how to change the theming and layout of pkgdown websites. Further work to improve user experience will involve: - 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 😉.