Styling page elements
Styling elements on the Openscapes website is accomplished using a mix of markdown syntax, Sass variables, and CSS rules. Sass variables and CSS rules are written in styles.scss (aka our "stylesheet"). A stylesheet(s) is applied to the site in the _quarto.yml file under the format section:
format:
html:
page-layout: full
theme:
- styles.scss # this is our stylesheet! you can add more than one stylesheet
mainfont: Sen # NOTE: we apply our website's main font here (Google font must be imported in styles.scss for this to work)
Read on for more information on conventions and some introductory tutorials (Note: for more background on Sass & CSS, check out these workshop slides).
It's easy to mix and match syntaxes throughout (and totally allowed) -- for consistency, we try to stick to the following conventions:
-
bolded text:
**bolded text** -
italicized text:
*italicized text* - define headers (levels 1 - 6) with pound symbols,
#(e.g.# level 1 header,## level 2 header,### level 3 header, etc.)
Sass variables make it easy to name hex color codes and reuse them throughout our stylesheet. Sass variables have the syntax $varName: value; and should be defined in styles.scss beneath the /*-- scss:defaults --*/ heading (all sass variables must live beneath this heading). The Openscapes website currently uses the following colors (which have been defined as Sass variables):
$white: #FFFFFF;
$light-gray1: #EEEEEE;
$light-gray2: #DBDBDA;
$medium-gray1: #999999;
$medium-gray2: #555555;
$dark-gray: #333333;
$blue: #38A7BB;
$light-blue: #53C9DF;
$light-yellow: #FFF6E1;
Define additional colors by adding to this list, or update existing color variables by changing the hex code values.
Quarto provides a number of predefined Sass variables which make it easy to update the website's overall theme (e.g. page background color, navbar/footer colors, hyperlink color, appearance of code blocks, etc.). These Sass variables should also be defined in styles.scss under the /*-- scss:defaults --*/ heading (all sass variables must live beneath this heading). Our stylesheet currently sets values to the following Quarto Sass variables (where the values are our color variables, described above):
(note: // is used to denote a code comment in a .scss file)
$navbar-bg: $white; // navbar background color
$navbar-fg: $dark-gray; // navbar foreground elements color (e.g. text)
$navbar-hl: $dark-gray; // highlight color for navbar links
$body-bg: $white; // page color background
$body-color: $dark-gray; // page text color
$footer-bg: $medium-gray2; // footer background color
$link-color: $blue; // hyperlink color
Explore additional Quarto Sass variables and add to the above list, if desired.
.scss files allow us to write both sass variables and css rules all in the same stylesheet (note: you can only write css in a .css file). CSS rules must be written under the /*-- scss:rules --*/ heading.
Here's the basic structure of a CSS rule:
where:
-
Selectors select the HTML element(s) you want to style (e.g. level one headings,
<h1>) -
Declarations sit inside curly brackets,
{}, and are made up of property and value pairs. Each pair specifies the property of the HTML element(s) you’re selecting (e.g. the color property of the element<h1>), and a value you’d like to assign to that property (e.g.green) - A property and its corresponding value are separated by a colon,
:. Declarations end with a semicolon,;
There are different types of CSS selectors, though this stylesheet currently defines only element selectors (like the example above) and class selectors:
-
Element selectors: these select all HTML elements with the specified element name (e.g. in the above example, all
<h1>elements will be the color green and include some additional spacing between letters -- note: even though we're using markdown syntax (#) to define our<h1>elements, this rule will still apply!). After writing a CSS rule (instyles.scss) using an element selector, you do not need to do anything else -- the rule will automatically be applied to any elements that match that selector (you can think of it as updating the default appearance of an HTML element). - Class selectors: these select elements with a specific class attribute. Class selectors are written using the following syntax:
.class {
declaration1: value;
declaration2: value;
}
Two example class selectors written/used in the Openscapes website are:
.blue-underline { // underline text with a blue line
text-decoration: underline $blue;
text-underline-offset: 10px;
text-decoration-thickness: 4px;
}
.center-text { // center text
text-align: center;
}
After writing a CSS rule (in styles.scss) using a class selector, you must apply them to the elements you'd like to style on your webpage .qmd files. Read on for instructions on how to apply classes to style elements.
Apply styles to sections of text using divs or spans:
Divs are used throughout the Openscapes website to style paragraphs using the syntax:
::: {.class}
My paragraph
:::
For example:
::: {.blue-underline}
This text will be underlined blue
:::
::: {.blue-underline .center-text}
This text will be underlined blue and centered on the page
:::
Note: rainbow divs are a new feature of the latest version(s) of RStudio (similar to rainbow parentheses) making it easier to keep track of the start and end of divs!
Another note: You can use HTML tags & selectors to style elements, but for consistency, we stick with the Quarto div syntax (above). The above example translates to the following HTML:
<p class="blue-underline">This text will be underlined blue</p>
<p class="blue-underline center-text">This text will be underlined blue and centered on the page</p>
Spans aren't used heavily (or at all?) yet in the Openscapes website, but they're an option worth knowing about! They use the syntax:
[some text]{.class}
For example:
Here is some text where just the last word is colored [blue]{.blue-text}
Note: You can use HTML spans to apply this type of inline styling, but for consistency, we stick with the Quarto span syntax (above). The above example translates to the following HTML:
<p>Here is some text where just the last word is colored <span style="blue-text">blue</span></p>
Below are a few class selectors defined in styles.scss and a .qmd file where those styles are applied to text elements using both divs and spans:
/*-- scss:defaults --*/
$medium-gray1: #999999;
$medium-gray2: #555555;
$blue: #38A7BB;
$light-yellow: #FFF6E1;
/*-- scss:rules --*/
.blue-underline {
text-decoration: underline $blue;
text-underline-offset: 10px;
text-decoration-thickness: 4px;
}
.medium-body-text {
font-size: 25px;
}
.caption-text {
font-size: 15px;
color: $medium-gray2;
}
.blue-text {
color: $blue;
}
.medium-gray1-text{
color: $medium-gray1;
}
.center-text {
text-align: center;
}
.yellow-bg {
background-color: $light-yellow;
padding-top: 5px;
padding-bottom: 5px;
padding-right: 5px;
padding-left: 8px;
border-radius: 15px;
}
---
title: ""
---
This is text that does not have any styling applied
::: {.blue-underline}
This text will be underlined in blue
:::
::: {.blue-underline .center-text}
This text will be underlined in blue and centered on the page
:::
<br> <!-- add a "break" to create space between elements on the page -->
'''{r}
#| eval: true
#| echo: false
#| out-width: "20%"
#| fig-align: "center"
#| fig-alt: "An orange fox wearing a purple baseball cap with the orange Openscapes logo on the front holds a white flag that says, 'Welcome!' in its outstretched arm."
knitr::include_graphics("images/minis/fox_hat.png")
'''
::: {.caption-text .center-text}
*This is caption text, which has a font size of 15px and font color gray. We also center it by adding the `.center-text` class selector. Bounding this text with single asterisks italicizes it.*
:::
::: {.yellow-bg}
Everything inside the `.yellow-bg` fences will fall within a yellow block to draw attention
::: {.medium-body-text .center-text}
We can nest divs within divs -- this text is larger and centered
:::
::: {.medium-gray1-text}
This text is mostly gray but the last word is colored [blue]{.blue-text}
:::
:::
