R/modify_default_highlighting.R
modify_default_highlighting.Rd
Create a syntax highlighting theme by modifying the default from the {distill} package and write it to the current working directory.
modify_default_highlighting(
name = "highlighting",
numeric = NULL,
strings = NULL,
functions = NULL,
control = NULL,
constant = NULL,
overwrite = TRUE
)
Name of the theme file (will be written as name.theme)
Colour for numeric variables. Must be either a named colour in grDevices::colors()
or of the hex form "#RRBBGG". Default is red "#AD0000" (approx "Bright Red").
Colour for strings. Must be either a named colour in grDevices::colors()
or of the hex form "#RRBBGG". Default is green "#20794D" (approx "Eucalyptus").
Colour for function names. Must be either a named colour in grDevices::colors()
or of the hex form "#RRBBGG". Default is purple "#4758AB" (approx "San Marino").
Colour for control (e.g. if
, while
). Must be either a named colour in grDevices::colors()
or of the hex form "#RRBBGG". Default is blue "#007BA5" (approx "Deep Cerulean").
Colour for constants (e.g. TRUE
, NULL
). Must be either a named colour in grDevices::colors()
or of the hex form "#RRBBGG". Default is brown "#8F5902" (approx "Chelsea Gem").
logical. If TRUE
(default), will overwrite name.theme
if it already exists in the working directory.
This is function modifies the default syntax highlighting theme from the {distill} package by replacing the five colours used in that scheme with colours of the user's choosing. It is not a fully-featured function to create a theme from scratch. However, it does place a .theme
file in your working directory which can be further modified if more customisations are desired. Note that if a hex code in the default is replaced with another hex code, that change in colour is applied. However, if a null
in the default is replaced with a hex code, that colour does not show up when the theme is applied.
We strongly recommend that when users choose colours for the syntax highlighting theme to be applied to their Distill website/blog, they take WCAG guidelines for web accessibility into account by ensuring that the colour contrast ratio between each of the colours used and background colour is at least 4.5:1. This can be checked with a tool such as WebAIM contrast checker or in R with savonliquide::check_contrast()
or the cr_get_ratio()
function from the coloratio
package, available on GitHub. We also recommend checking that your palette is colourblind-friendly, for example by using prismatic::check_color_blindness()
function.
There are two ways to apply a custom syntax highlighting scheme to a Distill site or blog:
Apply it site-wide by adding a theme
key to the top-level of your
_site.yml
configuration file (assuming the theme file is in your
root directory):
output:
distill::distill_article:
highlight: highlighting.theme
At least, that should work, but isn’t for the author at the time of writing. There is an open issue about this.
Apply to an individual article by adding a theme
key to your
article’s YAML front-matter, using the full path (assuming that the
.theme
file is in the site root directory), e.g.:
---
title: "My Highlighting Theme"
output:
distill::distill_article:
highlight: /Users/USER/WEBSITE/highlighting.theme
---
The second option allows for you to apply your theme to individual articles, while using a different theme for the rest of your site. Note that this is only possible for stand-alone articles within a website — you cannot apply a theme to individual blog posts only.
if (FALSE) {
modify_default_highlighting("my_highlighting",
"#B6005B", "#008643", "#005BB6", "#5A00B5", "#B65B00")
modify_default_highlighting("base_cols",
"red", "orange", "yellow", "green", "blue")
}