preferably

{preferably} is an accessible template for pkgdown documentation websites. It uses a light and a dark theme and utilizes the prefers-color-scheme CSS variable to automatically serve either of the two based on users' operating system setting, or allowing them to manually toggle between them.

Besides offering light and dark mode, I spent some time making the overall reading experience of 'pkgdown' documentations just a bit nicer, by using richer fonts, adopting a better color scheme for codes, etc.

Please let me know if you happen to use my template in your project. I'd like to keep a list of websites that are using 'preferably', see here: In the Wild!

Installation

You can download the stable version from CRAN using install.packages("preferably"), or you may download the development version from GitHub as follow:

install.packages("devtools"); library(devtools)

install.packages("preferably")

Usage

After the successful installation, if you already have your pkgdown setup ready, you only need to specify the template parameter as follow. Then, as before, you can build your site using build_site() and deploy it manually using deploy_on_branch().

template:
  package: preferably

{pkgdown} 2.0 and Bootstrap 5

{preferably} 0.4 is compatible with {pkgdown} 2.0 and Bootstrap 5. In order to build your website using the Bootstrap 5, your setting should look like this:

template:
  package: preferably
  bootstrap: 5

⚠️ Keep in mind that you should NOT use default_assets: false when you change the default template. 'preferably' relies on some of the 'pkgdown' assets and templates.

Integration

In the case that you are using CI systems to build and deploy your website, you need to make sure that 'preferably' is available on the environment. For GitHub Action, add the following line to the "Install dependencies" section of your .github/workflows/pkgdown.yaml file:

- name: Install dependencies
  run: |
    # ⚠️ leave other commands intact, 
    # and add the following command to the end of the list