Customizing Quarto Websites

Make your website stand out using Sass & Alternate CSS3 Logo



Sam Csik |
Data Training Coordinator
National Center for Ecological Analysis & Synthesis

Master of Environmental Data Science |
Fall 2022
Bren School of Environmental Science & Management


Slides & source code available on GitHub

Check Prerequisites
You should already have a Quarto website (or at least the bones of one) that:
angle-right is deployed using GitHub Pages and
angle-right contains some content (e.g. text, headings, etc.) for us to customize
Two penguins looking happily up at a Quarto logo 'meteor' that is flying overhead.
Art by Allison Horst
If you first need to get your website up and running, follow along with these step-by-step instructions before moving forward.

TL;DR

When we render a new Quarto site, it converts all of our markdown into HTML and applies a pre-built CSS stylesheet (the Bootswatch Cosmo theme). We can modify the appearance of our website in a number of ways. We’ll learn a bit about the following (but know that this is just a starting point!):
angle-right Editing the index.qmd YAML – you can apply a pre-built template to give your landing page a sleek and professional appearance (we can further modify this later with some CSS).
angle-right Editing the _quarto.yml file – here we can easily update our top navigation bar (e.g. add new pages), add a page footer, a favicon, Google Analytics, declare a main font, and more. We can also switch the default theme to a different pre-built Bootswatch theme (by replacing cosmo with an alternative theme name).
angle-right Defining CSS rules in the styles.css file that comes with every new Quarto site. This allows you to fine-tune the appearance of your site.
angle-right Creating a .scss file(s) that contains Sass variables to quickly customize your website’s theme – these take the form of $var-name: value; and you can find a list of them in the Quarto documentation.

Or….

TL;DR

Combine all of the above! Approaching this in the following order worked best for me:
angle-right First add a template to index.qmd, then fill out as much of the _quarto.yml file as you can/want – this is the easiest way to add some really cool features with minimal effort.
angle-right Next, create a mystyles.scss file (name it however you want), link to it in _quarto.yml (this applies your styles to your Quarto site), and define your Sass variables.
angle-right Finally make fine-tuned adjustments by defining CSS rules directly in your mystyles.scss file (you can write CSS in SCSS files, but not the other way around).

Code Branch Working on branches is recommended!
I almost always work on a branch when making changes to my website – this way I can safely test changes before deploying them to my live site.
To create a branch, first ensure that you’re on main by typing either git branch or git status into your RStudio terminal (either will tell you which branch you’re currently on). If you’re not on main, you can switch by running git checkout main.
Create a local git branch from main by running the following in your terminal:
git checkout -b my-new-branch
Push your new local branch to GitHub by running the following in your terminal:
git push -u origin my-new-branch
You’re now ready to work as normal! Once satisfied with your changes, you can git add, git commit, and git push (or use the RStudio GUI buttons in the Git tab) your files. Open a pull request from GitHub and merge into main to integrate your changes.

Palette Let’s start styling

So you’ve created your personal website using Quarto…

Quarto gives us with an easy-to-use web publishing format to create our personal websites – we can develop in a space that is comfortable (for me, that’s RStudio) and write mostly Markdown syntax (which is rendered as HTML when we build our website). A massive benefit is that these websites already look pretty slick right out of the box.


An example Quarto website styled using the built-in Bootswatch theme, Cosmo

But some additional modifications can make your website stand out from the rest
Alecia Keys, a judge on the TV show, The Voice, excited slams her hands down and stands up saying, 'There is nobody like you!'

Add a template to your index.qmd and edit _quarto.qmd

Turn your landing page into an “About Page” with a photo

---
title: "samantha csik" # if using a built-in template, this title appears under your photo
image: headshot.jpg # great spot for your professional headshot :) 
about: 
  template: trestles # see other templates at https://quarto.org/docs/websites/website-about.html#templates
  image-shape: rounded
  image-width: 15em
  links:
    - icon: linkedin # you'll need to the fontawesome extension to include icons: https://github.com/quarto-ext/fontawesome
      text: LinkedIn
      href: https://www.linkedin.com/in/samanthacsik/
    - icon: twitter
      text: Twitter
      href: https://twitter.com/SamanthaCsik
    - icon: github
      text: GitHub
      href: https://github.com/samanthacsik
    - icon: envelope
      text: Email
      href: mailto:scsik@ucsb.edu
---
Run quarto preview in your terminal window to view changes in near real time – each time your save your work, the preview will update in your browser.

Without an About Page template

With the trestles About Page template

angle-right Use the about option in the YAML section of index.qmd to turn your landing page into an About Page – supply it with one of five template options (here, I chose trestles). It is not necessary to do this (you can fully build/customize your web page layout using CSS), but it’s a fast way to create a clean, professional-looking landing page. NOTE: Any of your webpages can be turned into an About Page.
angle-right The links option under about allows you to create buttons underneath your landing page photo. You need to supply a text (as you’d like it to appear on the button) and an href (a link), and optionally can supply an icon.
angle-right You’ll need to install the quarto fontawesome extension to include icons throughout your site (including your About Page buttons). Run quarto install extension quarto-ext/fontawesome in your RStudio terminal. NOTE: You’ll need to install this for each project where you’d like to use fontawesome icons.

Add additional pages (& clickable icons) to your navbar & add a footer

project:
  type: website
  output-dir: docs

website:
  title: "samantha csik"
  navbar:
    title: samanthacsik # this is the website title as it appears in the top left corner -- clicking on this will jump you back to your landing page from where ever you are
    right: # align navbar items to the right/left/center
      - href: index.qmd
        text: home # use 'text' option to update the name as you want it to appear in your navbar
      - about.qmd
      - resources.qmd
      - href: CV/SCsik_CV.pdf
        text: cv
      - icon: github # add icons that link to social media, etc.
        href: https://github.com/samanthacsik
      - icon: twitter
        href: https://twitter.com/SamanthaCsik
    page-footer: 
    background: light
    left: 
      - "Copyright 2021, Samantha Csik"
    right: 
      - icon: github
        href: https://github.com/samanthacsik
      - icon: twitter
        href: https://twitter.com/SamanthaCsik

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
angle-right The navbar page names will appear as the title given to each .qmd file (e.g. in the YAML of about.qmd, the title option has the value about, and therefore appears in the navbar as “about”). However you can update the name as it appears in your navbar by providing the text option when linking your new page in _quarto.yml.
angle-right Link your resume or CV by providing a file path to the pdf in href (e.g. href: file/path/to/CV.pdf) and the text as you’d like it to appear in your navbar (see example provided). This will open up the browser-based pdf viewer when clicked. Be sure to provide the text option with the title as you’d like it to appear in your navbar.

Add a favicon & personal logo

project:
  type: website
  output-dir: docs

website:
  title: "samantha csik"
  favicon: file/path/to/image.png
  navbar:
    title: false # change this to false!
    logo: file/path/to/logo.png
    logo-alt: "Alt text for logo"
    right: 
      - href: index.qmd
        text: home 
        
      # ~ additional YAML excluded for brevity ~

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
angle-right Create your own logo using the free Adobe Express Logo Maker to include in the top left corner of your website (clicking on this will take you back to your site’s landing page) – provide Adobe with a little info about yourself, and it’ll return a bunch of AI-generated logos for you to choose from and customize further. I used this service to also create my favicon. Tip: You can download logos with a transparent background, or with a background that matches the color you plan to change your navbar to (as in this example). I also recommend making them as large as possible before downloading – doing so may circumvent having to adjust the logo size using CSS (I realized that after the fact Smiling Face ).

Checkout other website tools

Explore the Quarto documentation to learn more about enabling Twitter Cards, Google Analytics, Open Graph protocol, and more.


Use a Syntactically Awesome Stylesheet (Sass ) to define variables for use throughout your website

What is Sass?

Sass stands for Syntactically Awesome Stylesheets and is an extension to CSS (I know, it seems like we’re talking about this in an incorrect order, but bear with me).
Sass is a CSS preprocessor – this means that Sass allows web developers to use Sass syntax and features that don’t currently exist in CSS (e.g. variables, which we’ll be using today), then converts that Sass code into standard CSS (browsers don’t understand Sass code, but do understand CSS).
Quarto has a number of Sass Variables that you can specify within a mystyles.scss file.

Why use Sass?

Stylesheets (e.g. .css files) are getting larger and more complex. Sass extends existing CSS features and importantly, reduces repetition. For example, let’s say you’re working on a website, which uses 3 main colors:
You might imagine how often you’ll need to type those HEX codes out as you developing your stylesheet…it can get annoying rather quickly.

Why use Sass?

Sass allows us to define variables (in the form $var-name: value;) for our colors to reference instead of writing out their HEX codes each time:
/* -- define Sass vars --*/
$darkblue: #053660;
$teal: #147C91;
$darkgray: #333333;

/*-- use vars in CSS rules (we'll learn more about how to write CSS soon!) --*/
h1 {
  font-color: $darkblue;
}

.button-styling {
  background: $teal;
  color: $darkblue; 
  border-color: $darkgray;
}
If you decide that you actually like a different shade of teal better, you’ll only need to update the hex code where you first define the $teal Sass variable, saving lots of time.

Create a .scss file for your website

1. Create a .scss file in the root directory of your website’s repo using the touch command in the RStudio terminal:
touch mystyles.scss # name it whatever you want (you can apply more than one style sheet to your website)
2. Add the /*-- scss:defaults --*/ page divider to the top of mystyles.scss (this is important!) – you’ll write all your Sass variables underneath this.
/*-- scss:defaults --*/
3. Apply your mystyles.scss stylesheet to your website by updating the _quarto.yml under the format section:
project:
   # ~ additional YAML omitted for brevity ~

website:
  # ~ additional YAML omitted for brevity ~
  
format:
  html:
   theme: 
      - mystyles.scss
    toc: true

Create Sass variables for your website’s primary colors

We can quickly change the color theme of our website by defining just a few Sass variables in a .scss file. Let’s first define the colors we want to use throughout our site. For me, that looks like this:
/*-- scss:defaults --*/

// Colors
$light-sage-green: #D1D9CE;
$dark-sage-green: #98A08D;
$cream: #FDFBF7;
$gray: #64605f;
$light-gray: #949799;
$purple: #AE8BD1;
You can also define values with units, e.g. $my-font-size: 25px; or $my-width: 500px;.


In .scss files, // denote single line comments. Multi-line comments start with /* and end at the next */.

Use your color variables as values for Quarto’s list of Sass Variables

Quarto provides a list of Sass Variables that can be specified within .scss files. Let’s use our newly minted Sass color variables to change things like the background color, navbar & footer colors, hyperlink color, and more.
/*-- scss:defaults --*/

// Colors
$light-sage-green: #D1D9CE;
$dark-sage-green: #98A08D;
$cream: #FDFBF7;
$gray: #64605f;
$light-gray: #949799;
$purple: #AE8BD1;

// Base document colors
$navbar-bg: $cream; // navbar
$navbar-fg: $dark-sage-green; // navbar foreground elements
$navbar-hl: $purple; // highlight color when hovering over navbar links
$body-bg: $light-sage-green; // page background 
$body-color: $gray; // page text 
$footer-bg: $cream; // footer 
$link-color: $purple; // hyperlinks 

// Inline code
$code-bg: $cream; // inline code background color
$code-color: $purple; // inline code text color

// Code blocks
$code-block-bg: $cream; // code block background color
angle-right Okay, tell me that that doesn’t already look so much better?!
angle-right You don’t have to create a theme entirely from scratch! If you like parts of a pre-built Bootswatch theme (e.g. cosmo), you can modify it by layering on your desired updates. See the Quarto documentation for more details.

Import and apply new fonts font

Explore Google Fonts

With Quarto, we can define a single primary font directly in our _quarto.yml file:
format:
  html:
    theme: 
      - mystyles.scss
    mainfont: yourFontHere
    toc: true
To do so, we first need to choose and import any fonts we’d like to use throughout our website. Start by exploring the many fonts available at https://fonts.google.com/.


Selecting a Google Font(s)

1. Once you’ve found a font you’d like to use, scroll down to the Styles section of that font’s page – here you’ll (typically) find a number of different weights (e.g. thin, light, regular, bold) and styles (e.g. italic). Click on the + button, , to the right of the style you want. In this example, I choose Nunito in the Light 300 style, though you can choose as many fonts to import as you’d like.
2. Click on the View selected families button, , in the top right corner to see all of your selected fonts. Under the Use on the web section, select the radio button for @import and copy everything between the <style> </style> tags (starting with @import and ending with ;) to your clipboard.

Importing a Google Font(s)

To import a font, paste your copied clipboard into mystyles.scss
/*-- scss:defaults --*/

// Fonts
@import url('https://fonts.googleapis.com/css2?family=Nunito:wght@300&display=swap');

// Colors
$light-sage-green: #D1D9CE;
$dark-sage-green: #98A08D;
$cream: #FDFBF7;
$gray: #64605f;
$light-gray: #949799;
$purple: #AE8BD1;

// Base document colors
$navbar-bg: $cream; // navbar
$navbar-fg: $dark-sage-green; // navbar foreground elements
$navbar-hl: $purple; // highlight color when hovering over navbar links
$body-bg: $light-sage-green; // page background 
$body-color: $gray; // page text 
$footer-bg: $cream; // footer 
$link-color: $purple; // hyperlinks 

// Inline code
$code-bg: $cream; // inline code background color
$code-color: $purple; // inline code text color

// Code blocks
$code-block-bg: $cream; // code block background color

Using a Google Font(s)

To apply an imported font as a primary font, update _quarto.yml with the font name.
format:
  html:
    theme: 
      - mystyles.scss
    mainfont: Nunito
    toc: true
angle-right If you plan to use multiple fonts, you can create Sass variables for each font type, then use those variables as you construct your CSS rules. For example, this slide deck uses three fonts (Sanchez, Montserrat, and Roboto Mono):
// Fonts
@import url('https://fonts.googleapis.com/css2?family=Lato&family=Montserrat&family=Nunito+Sans:wght@200&family=Roboto+Mono:wght@300&family=Sanchez&display=swap');

// Fonts
$font-family-serif: 'Sanchez', serif; 
$font-family-sans-serif: 'Montserrat', sans-serif;
$font-family-monospace: 'Roboto Mono', monospace;

With just a few YAML additions and a handful of Sass variables, we’ve already really transformed the appearance of our website. Next up: refining.

Enter HTML and CSS
In order to really fine-tune the appearance of our site, we need to dive a bit into the world of HTML and CSS.
The CSS 3 and Sass logos
Some of you may have already heard of/written HTML and/or CSS – that’s great! We’re going to spend a few minutes first learning about what makes a web page…look like a web page, then apply what we learn to our own Quarto sites.

HTML & CSS are the building blocks of web pages
HTML (Hypertext Markup Language) is a markup language1 that tells web browsers how to structure web pages. You can think of HTML as the skeleton of a web page. It gives authors the means to create elements like headings, text, tables, lists, add media, etc.
Source: Adapted from Nicolas Karasiak, https://github.com/nkarasiak/Illustration
1Markdown and R Markdown are both lightweight markup languages – they’re a bit easier for humans to write and read than HTML. HTML is more expressive and allows for customization that is difficult or impossible to do in Markdown.

HTML & CSS are the building blocks of web pages
CSS (Cascading Style Sheets) is a programming language that allows you to control how HTML elements look on a web page. You can think of CSS as the outfit that is styling the skeleton. It allows authors to control aspects such as the colors, layout, and font style.
Source: Adapted from Nicolas Karasiak, https://github.com/nkarasiak/Illustration

Your browser has its own internal style sheet to render HTML
Your browser will style HTML documents using an internal style sheet, which ensures that headings are larger than normal text, links are highlighted, lists and tables are structured correctly, etc.
HTML
Browser default styling

CSS adds pizzazz to web page renderings
CSS allows website developers to add additional styling to web browser defaults. Otherwise, websites would be pretty boring to look at (and they’d all generally look the same).
Browser default styling
CSS styling

A light introduction to HTML HTML 5 Logo

HTML elements
HTML consists of a series of elements comprising start tags and end tags that render some form of content in a particular way.
The basic anatomy of an HTML element:


In Markdown syntax, this HTML element would be written as:
# Welcome to your website customization workshop
Note: Some HTML elements have no content (e.g. the <br>, or “break” element) – these are called empty elements and do not have an end tag.

Commonly used HTML tags
Browse a complete list of HTML tags here.
Tag What it does
<div></div> defines a division or section in an HTML document
<h1></h1> create a first-level heading (largest)
<h6></h6> create a sixth-level heading (smallest)
<p></p> begin a new paragraph
<strong></strong> bold text
<em></em> italicized text
<img></img> present an image
<a></a> define a hyperlink
<br> add a line break (empty element)
<span></span> an inline container used to markup part of a text or document

HTML nested elements
You can also nest elements. Remember to close out tags from the inside-out to avoid unexpected renderings.
Nested HTML elements:


In Markdown syntax, this HTML element would be written as:
# Welcome to your **website customization** workshop
Important: Take extra care to never skip (or incorrectly type) an end tag! Some elements will still display correctly if you forget an end tag, but you cannot rely on this. Forgotten end tags will cause you headaches as you try troubleshoot unexpected results and errors Grinning Face With Sweat .

HTML attributes
HTML elements can also have attributes which provide extra information about elements. They are always specified in the start tag and usually come in value/name pairs (e.g. attributeName="attributeValue").
Attributes can be used in many powerful ways – one way is to provide a class or ID as an identifier to be used for targeted styling with CSS. We’ll come back to this concept soon.
The basic anatomy of an HTML attribute:

Laptop Code Practice writing some HTML HTML 5 Logo

In the following exercise, we’ll be creating a .html file (and eventually, a .css file to style it). This is meant only to help us familiarize ourselves with HTML syntax and does not have anything to directly do with our Quarto websites — feel free to delete this file(s) later, or keep as a reference!

Exercise: practice writing HTML (1/2)
You can use any text editor to do so (RStudio and VS Code work too!). The following steps assume you’re working in RStudio. Later, we’ll link an external (separate) CSS stylesheet within our HTML file to style our elements.
  1. Open an RProject (it’s fine to work on your website branch!). In your terminal window, use the touch command to create an HTML file (for simplicity, I did this in my project’s root directory), then choose Open in Editor.
touch practice-html.html
  1. Create the skeleton of your HTML file.
<!DOCTYPE html> <!-- All HTML docs start with a doc type declaration-->
<html> <!-- This tag represents the root of the HTML doc -->
<head> 
  <!-- Write any metadata about the HTML doc here (inluding the link to an external CSS file) -->
</head>
<body> 
  <!-- Write all the contents of the HTML doc here -->
</body>
</html>

Exercise: practice writing HTML (2/2)
Write some HTML! We’ll practice styling our HTML in the next section.
  1. Create a level one header, a paragraph, and a button (here’s one good resource on how to do that) that takes you to the MEDS website within the <body> of your html file.
<!DOCTYPE html> <!-- All HTML docs start with a doc type declaration-->
<html> <!-- This tag represents the root of the HTML doc -->
<head>
 <!-- Write any metadata about the HTML doc here (inluding the link to an external CSS file) -->
</head>
<body> 
  <!-- Write all the contents of the HTML doc here -->
</body>
</html>

Exercise: practice writing HTML (2/2)
Write some HTML! We’ll practice styling our HTML in the next section.
  1. Create a level one header, a paragraph, and a button (here’s one good resource on how to do that) that takes you to the MEDS website within the <body> of your html file.
<!DOCTYPE html> <!-- All HTML docs start with a doc type declaration-->
<html> <!-- This tag represents the root of the HTML doc -->
<head>
 <!-- Write any metadata about the HTML doc here (inluding the link to an external CSS file) -->
</head>
<body> 
  <!-- Write all the contents of the HTML doc here -->
  <h1>Here is my level one header</h1>
  <p>Here is my first paragraph</p>
  <p>Here is my second paragraph</p>
  <button type="button" onclick=window.location.href='https://ucsb-meds.github.io'>Go to MEDS website</button>
</body>
</html>
  1. Click on the Preview button at the top of your source pane to see the rendered output.

A light introduction to CSS Alternate CSS3 Logo

CSS is a rule-based language
CSS is a rule-based language, meaning that it allows you to define groups of styles that should be applied to particular elements or groups of elements on a web page. For example, “I want all level one (<h1>) headings to be green text with a bit of extra space between each letter” could be coded as:
angle-right Selectors select the HTML element(s) you want to style (e.g. level one headings, <h1>)
angle-right 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)
angle-right A property and its corresponding value are separated by a colon, :. Declarations end with a semicolon, ;

There are a number of different CSS selector types
The next few slides review just a few basic CSS selector types for styling HTML elements – these will get you far in your website customization journey (but you can learn more about all the different categories of CSS selectors here):
angle-right Element selectors
angle-right Grouping selectors
angle-right ID selectors
angle-right Class selectors
angle-right Universal selector
angle-right Inline styling (not a selector type, but an alternative way to apply CSS styling)

Select an element(s) based on its tag
Any HTML element can be used as a selector. The declarations specified apply to all HTML elements of that type.
CSS
h1 {
  color: green;
  letter-spacing: 5px;
}
HTML
<h1>My level one header will be styled</h1>
<h2>This level two header will not be styled</h2>
<p>Neither will this paragaph</p>
<h1>But this second level one header will be</h1>


Output
Rather than defining separate rules for multiple element selectors that you want styled the same way, you can group them together. Simply separate each selector by a comma.
CSS
h1, h2, p {
  text-align: center;
  color: purple;
}
HTML
<h1>My level one header will be styled</h1>
<h2>This level two header will be styled</h2>
<h3>This level three header will not be styled</h3>
<p>This paragraph will be styled</p>


Output

Select an element(s) using attributes
An ID selector uses the id attribute of an HTML element to style that specific element. IDs must be unique within a page and therefore can only be used to select and style one unique element. ID selectors are written using a # followed by the selector name, e.g. #selector.
CSS
#para1 {
  color: red;
  text-align: center;
}
HTML
<p id="para1">My first paragraph is styled</p>
<p>But my second paragraph is not</p>


Output
A class selector uses the class attribute of an HTML element to style that specific element. Class selectors are written using a . followed by the selector name, e.g. .selector. HTML elements can have more than one class, e.g. <p class="class1 class2">
CSS
.blue-italicized {
  color: blue;
  font-style: italic;
}
HTML
<p class="blue-italicized">My first paragraph is styled</p>
<p>But my second paragraph is not</p>


Output
If you’re like me, you’ll probably find yourself using class selectors most often!

Select all elements or style inline
The universal selector selects all HTML elements on the page. It is written using only an asterisk, *.
CSS
* {
  text-align: center;
  color: orange;
}
HTML
<h1>My level one header will be styled</h1>
<h2>This level two header will be styled</h2>
<p>This paragaph will also be styled</p>


Output
The style attribute may be used inline to apply unique styles to a single element. It’s best practice to use these sparingly as it mixes content (HTML) with presentation (CSS) and cannot be reused with other elements like defined CSS rules can.
HTML with inline styling
<p>This is a normal paragraph</p>
<p style="color: red; font-style: italic;">This paragraph has inline styling</p>
<p>Here, only the word <span style="color: red; font-style: italic;">paragraph</span> is styled</p>
Output

Conflicting CSS rules?
It is often the case that more than one CSS rule will point to the same element. For example, say you have a style sheet and HTML that look like the following:
CSS
* {
  color: orange;
}

h1 {
  color: blue;
}

.green-text {
  color: green;
}
HTML
<h1>This is my header</h1>
<p>This is my paragraph with <span style="green-text">some green text</span></p>
In this case, we have a universal selector that styles all of our text orange, but we also have an element selector that colors our <h1> elements blue and a class selector that is applied inline to color a subset of text green. How do you know which style will be declared and applied to each of our HTML elements?

The highest specificity value “wins”
Specificity can be complicated (especially when you consider all the other types of selectors we haven’t covered in these slides). For the purposes of this workshop and getting started on your CSS journeys, a general rule of thumb is as follows: Inline styles are the most specific and will override ID selectors, which will override class selectors, which will override element selectors, etc. The order that rules are written in your stylesheet matters as well – since rules are read top to bottom, a directly competing rule farther down your stylesheet will take precedent.

Inline Styles
IDs
Class Selectors
Element Selectors
Universal Selector

Laptop Code Practice writing some CSS rules to style your HTML elements Alternate CSS3 Logo

Exercise: practice writing CSS (1/3)
  1. Return to your RProject (where you created your practice-html.html file). In your terminal window, use the touch command to create a CSS file in the same location as your html file:
touch practice-styles.css
  1. Link your CSS file inside the <head> of your HTML file (read more about inserting style sheets here).
<!DOCTYPE html> <!-- All HTML docs start with a doc type declaration-->
<html> <!-- This tag represents the root of the HTML doc -->
<head>
 <!-- Write any metadata about the HTML doc here (inluding the link to an external CSS file) -->
 <link rel="stylesheet" href="practice-styles.css"> 
</head>
<body> 
  <!-- Write all the contents of the HTML doc here -->
  <h1>Here is my level one header</h1>
  <p>Here is my first paragraph</p>
  <p>Here is my second paragraph</p>
  <button type="button" onclick=window.location.href='https://ucsb-meds.github.io'>Go to MEDS website</button>
</body>
</html>

Exercise: practice writing CSS (2/3)
  1. Write some CSS selectors in your practice-styles.css file and save. Update your HTML file accordingly to apply your styles and Preview practice-html.html to see the updates. Some suggestions:
(a) create an <h1> element selector that styles the background color to something of your choosing (hex and rgb codes allowed!) and centers the text on the page,
(b) create a class selector to color the text of your first paragraph blue,
(c) use that same class selector inline to style just the word second (in your second paragraph) blue,
(d) create a class selector to color your button text red and enlarge the font size (try 20px),
(bonus) What happens if you also apply that red/large font selector (from part (d)) to your second paragraph?


Explore a list of all CSS properties here.


(One) solution on next slide!

Exercise: practice writing CSS (3/3)

Below is one solution – yours may look different!

h1 {
  background-color: #49bf96;
  text-align: center;
}

.blue-text {
  color: blue;
}

.large-red-text{
  color: red;
  font-size: 20px;
}
<!DOCTYPE html> <!-- All HTML docs start with a doc type declaration-->
<html> <!-- This tag represents the root of the HTML doc -->
<head>
 <!-- Write any metadata about the HTML doc here (inluding the link to an external CSS file) -->
  <link rel="stylesheet" href="practice-styles.css"> 
</head>
<body> 
  <!-- Write all the contents of the HTML doc here -->
  <h1>Here is my level one header</h1>
  <p class="blue-text">Here is my first paragraph</p>
  <p class="large-red-text">Here is my <span class="blue-text">second</span> paragraph</p>
  <button type="button" class="large-red-text" onclick=window.location.href='https://ucsb-meds.github.io'>Go to MEDS website</button>
</body>
</html>

Question Okay, but what about Quarto?

When you create a new Quarto site, it automatically creates a styles.css file


We can write our CSS rules in styles.css, but alternatively, we can write them directly in our mystyles.scss file (remember, you can write CSS in a .scss file but you can’t write Sass in a .css file). You can delete styles.css if you don’t plan to use it, or leave it be (it’s easy to create a new one using the touch command in your terminal).

Create a section for defining CSS rules in mystyles.scss
To start defining CSS rules in mystyles.scss you first need to add the /*-- scss:rules --*/ section divider beneath your Sass variables section:
/*-- scss:defaults --*/
// Fonts
@import url('https://fonts.googleapis.com/css2?family=Nunito:wght@300&display=swap');

// Colors
$light-sage-green: #D1D9CE;
$dark-sage-green: #98A08D;

// additional Sass variables omitted for brevity

/*-- scss:rules --*/
Next, we’ll walk through some examples of how to modify your site with your own CSS rules.

Determine which element you want to style

Let’s say I want to similarly style (add spacing between each letter, increase the font weight, make a dark gray color) the following text on my website:
On my landing page, I want to style my name, “samantha csik”, and the three section headers, “hi there!”, “education”, and “experience”
On my about page, I want to style the top header, “about”
On my resources page, I want to style the top header, “resources”

But what if I don’t know what HTML element type this is? Inspect!


Using the Inspect tool is a great way to get a better sense of how CSS is used to modify particular HTML elements (this works with any web page, and also your locally hosted website preview).
In your website preview, right click on an element of interest (in this case, let’s start with my name, “samantha csik”) and choose Inspect to pull up the underlying HTML & CSS files.
Hovering your mouse over different lines of HTML highlights the corresponding element on your webpage.

My name is an <h1> element

Note: This <h1> element also has a class title – more on that in a minute.

My landing page section, “education” (as well as “hi there!” and “experience”) are <h3> elements

My about page title (as well as my resource page title) are <h1> elements

Write a CSS grouping selector to style <h1> and <h3> elements

Here, we have a grouping selector that targets all <h1> and <h3> elements – it increases both the spacing between each letter and the font weight (makes it bolder), and it colors those header levels gray (reminder: I created a Sass variable: $gray: #64605f;).
/*-- scss:rules --*/

h1, h3 {
  letter-spacing: 5px;
  font-weight: 700;
  color: $gray;
}
No CSS styling on h1 and h3 headers
With CSS styling on h1 and h3 headers
angle-right I don’t need to make any changes to the HTML (in index.qmd, about.qmd, and resources.qmd since this grouping selector targets all <h1> and <h3> elements across my site. If an element on any of my pages has either of those tags, it will get styled with the declarations included in our CSS rule.

What’s with that title class selector?

Note how the page headers (“samantha csik” on the landing page, and “about” and “resources” on those respective pages), which all happen to be <h1> elements, are also of class, title.
The Quarto framework has defined a class selector called .title and applied that class to the above elements. We can modify it however we’d like. For example, let’s turn text elements of class title the color red:
/*-- scss:rules --*/

h1, h3 {
  letter-spacing: 5px;
  font-weight: 700;
  color: $gray;
}

.title {
  color: red;
}
angle-right In this case, I don’t need to make any changes to the HTML (in index.qmd, about.qmd, and resources.qmd) since those <h1> elements are already assigned the class, title.

Okay, but what about <h1> elements that are not of class title?

Let’s write a couple of other elements that are not of class="title" to see what happens. I’ll do this on my about page:
---
title: "about"
---

<h1>this is an `<h1>` element</h1> # alternatively, you can write <h1> elements using markdown (`# this is an `<h1>` element`)

<h1 class="title">this is an `<h1>` element of class `title`</h1>

<p>this is a `<p>` element</p>

<p class="title">this is a `<p>` element of class `title`</p>
angle-right You can add elements on your web pages using either RMarkdown/Markdown syntax (e.g. use # text here to denote an <h1> element) or use HTML tags (e.g. use <h1>text here</h1>). I tend to use a mix of both Markdown syntax and HTML tags.
angle-right Class selectors allow us to customize exactly how CSS rules apply to particular elements. In this example, only <h1> elements that are of class title are colored red. Any <h1> elements that are not of class title are styled according to our h1, h3 {} element selector.
angle-right We can apply the title class to any text element. In this example, we apply it both to an <h1> element and a <p> element.

Write your own class selector

Let’s create a class named custom-subtitle that styles text in the following ways: increases font size, italicizes it, and colors it purple. We can then add an element to our resources page and apply our new class selector:

/*-- scss:rules --*/

h1, h3 {
  letter-spacing: 5px;
  font-weight: 700;
  color: $gray;
}

.title {
  color: red;
}

.custom-subtitle {
  font-size: 22px;
  font-style: italic;
  color: $purple;
}

Here, I’m creating two paragraphs – one that is styled as a custom-subtitle and one that is not.

What happens if you create your custom subtitle using an <h1> tag instead of <p>? Why do you think this happens?

---
title: "resources"
---

<p class="custom-subtitle">Here is my custom subtitle.</p>

<p>And here is some normal text beneath it.</p>
angle-right Remember, class selectors take the form .selector-name {}

Apply a second class selector our text styled as a custom-subtitle

Let’s say we want the option to add a bit of extra space beneath this particular custom subtitle before the element is rendered – but maybe we don’t always want that extra space beneath every custom subtitle. If we were to add a declaration that increases margin-bottom directly to our .custom-subtitle class selector, all elements of class custom-subtitle would have that extra space.

One solution, then, is to create a new class selector (we’ll call it .bottombr, for “bottom break”) that we can specifically apply to our custom subtitle on the resources page.

/*-- scss:rules --*/

/* Additional rules/electors omitted for brevity */

.custom-subtitle {
  font-size: 22px;
  font-style: italic;
  color: $purple;
}

.bottombr {
  margin-bottom: 3em;
}

Here, we add our bottombr class selector within the "" after custom-subtitle and a space.

---
title: "resources"
---

<p class="custom-subtitle bottombr">Here is my custom subtitle.</p>

<p>And here is some normal text beneath it.</p>
angle-right Remember, HTML elements can have more than one class, e.g. <p class="class1 class2 etc">

Apply class selectors to page elements using Quarto’s own syntax

The following will be rendered the same way:

<tag class="myclass">Some text</tag> == [Some text]{.myclass}

I tend to use a mix of both approaches (HTML & Quarto syntax). In some situations using Quarto’s []{} feels cleaner. In other situations, I can get finer control over the styling of elements using HTML.

---
title: "resources"
---

<p class="custom-subtitle">Here is my custom subtitle.</p>

<p>And here is some normal text beneath it.</p>

[Here is another custom subtitle written with Quarto syntax]{.custom-subtitle}

Also note that I do not need to wrap this text in the `<p>` tag in order for it to render as normal text. `.qmd` files allow us to seamlessly blend markdown syntax with HTML.
angle-right You’ll notice the []{} syntax throughout Quarto’s documentation, and also if you explore the source code of other Quarto websites/presentations/etc. You don’t need to use it, but it helps to know what it is when you see it!

Lightbulb Get inspired

Styling your website can be challenging

^ How I feel most of the time while trying to write CSS


…and honestly, a lot of it is trial and error. Inspecting (reminder: right-click on an element in your website preview and choose “Inspect”) your website can take patience and persistence to figure out how exactly to target your desired element.


Luckily, there are ways to help yourself along.

Check out source code (specifically the stylesheets) of other sites


angle-right Learn from others! Exploring the source code for other websites, presentations, etc. is, in my opinion, critical for learning this new skill and applying it to your own work.


angle-right More and more Quarto websites are popping up all the time – keep an eye out on Twitter for folks sharing their sites! (I’ll never stop obsessing over Maya Gans’ Quarto site). You can also explore the source code and stylesheets for Quarto presentations (cough cough, like this very presentation), books, and more.


angle-right And don’t limit yourself to Quarto sites! Check out The Distillery Showcase, which links to a long list of websites built with R’s distill package (Note: the distill framework is a bit different – when exploring .css files, look for CSS selectors beneath the section /*-- Additional custom styles --*/).

Inspecting web pages allows you to temporarily “edit” CSS

Play around with selectors and update declaration values (or add/remove declarations) while inspecting your website. This not only allows you to try out styles before actually hard-coding them, but it also helps you identify exactly which elements different selectors are manipulating. Note that these changes are only temporary – refreshing your web browser will revert your site back to it’s original state.

Take advantage of interactive tutorials

W3Schools has tons of great examples and interactive tutorials for learning CSS. Touching (and breaking) code is one of the best ways to learn!


Now get to customizing!