Modify the default distill syntax highlighting theme — modify_default

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
)

Arguments

name: Name of the theme file (will be written as name.theme)
numeric: 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").
strings: Colour for strings. Must be either a named colour in grDevices::colors() or of the hex form "#RRBBGG". Default is green "#20794D" (approx "Eucalyptus").
functions: 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").
control: 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").
constant: 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").
overwrite: logical. If TRUE (default), will overwrite name.theme if it already exists in the working directory.

Details

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.

Examples

if (FALSE) {
modify_default_highlighting("my_highlighting",
    "#B6005B", "#008643", "#005BB6", "#5A00B5", "#B65B00")
modify_default_highlighting("base_cols",
    "red", "orange", "yellow", "green", "blue")
}