{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!
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")
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
{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.
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 👇🏼
remotes::install_deps(dependencies = TRUE)
install.packages("pkgdown", type = "binary") install.packages("preferably")
If you are using Travis-CI, add the following line to your
.travis.yml
file:
r_github_packages:
- amirmasoudabdol/preferably
In addition of pkgdown customization, Preferably offers a few more options as listed here.
Preferably allows for adding a custom analytic (in addition to
ganalytics
) to your website via the canalytic
option.
template:
package: preferably
params:
canalytic:
domain: example.com
src: https://example.com/tracker.js
Setting these command will generate the following line in the HTML:
<script async defer data-domain="example.com" src="https://example.com/tracker.js"></script>
{pkgdown}
2.0 comes with a greater list of supported trackers that you can use out of the box, including Plausible.
In addition to the automatic color scheme switching, you can add a
switch to the menu bar, e.g, , to
allow for manual selection between light and dark themes. This can be
done by setting the toggle
option to
manual
.
template:
package: preferably
params:
toggle: manual
Unfortunately, it is not possible to have both the automatic and manual mode at the same time. There is an user experience issue here, and it is almost impossible to deliver a seamless experience without involving the server-side, here, and here. So, you need to choose whether you like to give your users a manual toggle, or let your website adapts to their system preference.
⚠️ In order to remove the toggle button, remove the
toggle
parameter.
The goal of preferably
is to improve the accessibility
and readability of your documentation websites.
My main focus is to keep preferably
light and compatible
with pkgdown
. Besides, I have a short list of features that
I would like to add to template files, and pkgdown
package.
For those, I prefer to prepare a few pull requests and add them to
pkgdown
instead of diverging the preferably
from its core. Let’s see when I get to them! Here is a few:
If you found any bugs, or have any suggestions, please feel free to reach out to me, either by opening an issue or a pull request, or dropping an email.
If you enjoy using {preferably}, please consider supporting it on GitHub. You can sponsor me monthly, or make a one-time donation! 🤗