Latest news from the R Markdown family

Using CSS to style an html_document

Let’s start with a simple single document with this in the YAML:

---
output:
  html_document:
    css: custom.css
---

Inside that .css file, you could define CSS custom properties for some colors, then use them inside a simple CSS rule like my-color:

:root {
  --green: #212D2C;
  --sky: #A9FDFF;
}

.my-color {
  background-color: var(--green);
  color: var(--sky); 
  padding: 1em;
}

To apply your CSS rules in the body of your document, you could write raw HTML:

This is a <span class="my-color">color</span> word.

would produce…

This is a color word.

This works, but can clutter up your .Rmd with HTML. Instead, you may achieve the same result writing with Pandoc’s bracketed Spans, which allows you to keep your markdown text cleaner:

This is a [color]{.my-color} word.

would produce…

This is a color word.

To apply CSS to a full sentence, or even longer text, you can create divs using Pandoc’s fenced Div blocks:

::: {.my-color}
All of these words are colored.
:::

would produce…

Now, so far this is still a plain .css file- nothing too fancy yet! Let’s make it a .scss file instead, and add some fancier logic.

Using Sass to style an html_document

We’ll refactor our previous CSS from above to sass-ify it. We’ll use the SCSS (Sassy CSS) syntax. Sassy CSS builds on the existing syntax of CSS, and is a good way to get started using Sass because any valid CSS is also valid SCSS. The first thing we’ll do is save our file now with the .scss file extension:

---
output:
  html_document:
    css: custom.scss # update this!
---

Just like CSS, SCSS uses semi-colons and curly braces. The main difference is that we’ll use the $ symbol to make something a variable:

$green: #212D2C;
$sky: #A9FDFF;

.my-color {
  background-color: $green;
  color: $sky;
  padding: 1em;
}

We apply the style in the exact same way as before:

This is a [color]{.my-color} word.

would produce…

This is a color word.

But there is still a lot more that we can do. Among other things, Sass allows you nest your CSS selectors in a way that follows the same visual hierarchy of your HTML. This can make your CSS rules easier to read and write. Let’s add a simple nested rule to change the link text color to a new variable $green:

$green: #212D2C;
$sky: #A9FDFF;
$cyan: #36C9B4;
  
.my-color {
  background-color: $green;
  color: $sky;
  padding: 1em;
  
  a {
    color: $cyan;
  }
}

Let’s switch to using Pandoc divs in the body of our document to apply this style:

::: {.my-color}
This is a link that will be [green](https://pkgs.rstudio.com/rmarkdown/).
:::

would produce…

Sass also provides additional processing abilities like @extend rules, which you’d use when one class should have all the styles of another class, as well as its own specific styles.

Let’s separate my-color now from a new class called my-link. This new class will do some clever, sassy things:

1. Build on the my-color class with the @extend rule,

2. Add a unique $cyan for link text,

3. Add hover effects for links using the Sass parent selector, &, and

4. Use the Sass rgba() color function to apply an alpha level to our existing $green color variable (note that it begins life as a hex color!).

$green: #212D2C;
$sky: #A9FDFF;
$cyan: #36C9B4;
  
.my-color {
  background-color: $green;
  color: $sky;
  padding: 1em;
}

.my-link a {
  @extend .my-color;
  color: $cyan; 

  &:hover {
      background-color: rgba( $green, .5 );  
      color: white;
  }
}

::: {.my-link}
This is a link that will be [cyan](https://pkgs.rstudio.com/rmarkdown/).
:::

would produce…

Now we’ve made it so links will have a lighter background color upon hover, and the text turns white. One more little thing: Pandoc also works with ID attributes. Let’s add a special ID selector for links with the cookbook ID. We’ll start the rule with the hash (#) character (instead of the . we used for classes), followed by the id of the element.

#cookbook a {
  text-decoration-style: wavy;
}

::: {#cookbook}
This is a link that will be [wavy](https://bookdown.org/yihui/rmarkdown-cookbook/).
:::

would produce…

You can combine IDs, classes, and even nest bracketed spans inside fenced divs. Let’s do it all!

::: {.my-link}
This is a link that will be [cyan](https://pkgs.rstudio.com/rmarkdown/), 
but you can read more in [[The Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/)]{#cookbook}.
:::

would produce…

We hope this short walk-through inspires you to test out this new feature, and consider how using Sass might help you customize your HTML-based outputs with R Markdown. To learn more, check out the sass R package vignette. Look out for our future blog posts and resources that will showcase how to use these features with R Markdown.

For shorter styling rules, you could instead use knitr’s sass or scss engines (also powered by the sass package) to provide those rules inline in a code chunk (without lugging around a separate external style file in your project). Thanks to Emily Reiderer for this contribution!

The sass/scss code chunks are compiled through the sass::sass() function. This means you can write Sass code directly into a code sass chunk and the resulting CSS will be included in the output document. For example, this kind of code chunk can exist anywhere in your .Rmd to add styles:

```{scss}
$green: #212D2C;
$sky: #A9FDFF;
$cyan: #36C9B4;
  
.my-color {
  background-color: $green;
  color: $sky;
  padding: 1em;
}
```

When you knit, the style will be applied to the whole document, so you can put these chunks at either the top or bottom of your .Rmd and they will work the same way (i.e., styles will be applied to all content, not just content below the sass/scss chunk). You can read more about these knitr engines in the R Markdown Cookbook.