You should already have a Quarto website (or at least the bones of one) that:
is deployed using GitHub Pages and
contains some content (e.g. text, headings, etc.) for us to customize
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.
Quarto gives us 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 and trestles layout template applied
index.qmd
---
title: "Samantha Csik" # if using a built-in template, this title appears under your photo
image: media/headshot.jpg # great spot for your professional headshot :)
toc: false # remove "On this page" table of contents
about:
template: trestles # see other templates at https://quarto.org/docs/websites/website-about.html#templates
image-shape: round
image-width: 20em
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 you save your work, the preview will update in your browser.
Without an About Page template
With the trestles About Page template
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 web pages can be turned into an About Page.
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/or an icon, as well as an href (a URL or file path to another page or file) for your button to redirect to.
You’ll need to install the Quarto fontawesome extension if you’d like to include icons throughout your site (including your About Page buttons). Run quarto install extension quarto-ext/fontawesome in your RStudio Terminal, which downloads the extension files and saves them to your project directory (you should see a new folder, _extensions/quarto-ext/fontawesome/ in your project directory). NOTE: You’ll need to install this for each project where you’d like to use fontawesome icons.
Any edits you want to make to your navbar happen under the website: > navbar: option in your _quarto.yml file.
_quarto.yml
project:
type: website
output-dir: docs
website:
navbar:
title: "Samantha Csik" # 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
- href: resources.qmd
text: Resources
- href: cv/myCV.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
format:
html:
theme: cosmo
css: styles.css
toc: true
Right/center/left align your navbar contents using the website: > navbar: > right/center/left: option. Add navbar pages as an indented list beneath this option.
Navbar page names will appear the same 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”). You can update the name as it appears in your navbar by providing the text option when linking your new page in _quarto.yml (see “Home” and “Resources” pages as examples).
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.
Any edits you want to make to a website footer happen under the website: > page-footer: option in your _quarto.yml file.
_quarto.yml
project:
type: website
output-dir: docs
website:
navbar:
title: "Samantha Csik" # 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
- href: resources.qmd
text: Resources
- href: cv/myCV.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 # or dark
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
Footers appear on each page (you may have to scroll to the bottom to see it appear). You can include a mix of text, icons, logos, hyperlinks, etc.
A favicon is a small icon used on web browsers to represent a website or a web page. Get creative and use a custom favicon that complements your personal logo.
_quarto.yml
project:
type: website
output-dir: docs
website:
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
page-layout: full
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 so that they can be placed anywhere on your site without having to deal with mismatched background colors. I also recommend making them as large as possible before downloading – doing so may circumvent having to adjust the logo size using CSS.
Explore the Quarto documentation to learn more about enabling Twitter Cards, Google Analytics, Open Graph protocol, and more.
Syntactically Awesome Stylesheets
- Sass is a CSS extension (provides additional features, like variables)
- Sass is a CSS preprocesser (converts Sass code into standard CSS because browsers can’t interpret Sass)
I know it might feel like we’re getting ahead of ourselves a bit here, but bear with me!
Sass extends existing CSS features in a number of exciting ways, but importantly reduces repetition. For example, let’s say you’re working on a website/web page that uses three 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.
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.
styles.scss
/*-- scss:defaults --*/
// Colors
$dark-green: #858E79;
$light-green: #D1D9CE;
$cream: #FDFBF7;
$gray: #64605f;
$purple: #9158A2;
$orange: #ad7237;
// Base document colors
$navbar-bg: $cream; // navbar
$navbar-fg: $dark-green; // navbar foreground elements
$navbar-hl: $purple; // highlight color when hovering over navbar links
$body-bg: $light-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
Okay, tell me that that doesn’t already look so much better?!
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.
With Quarto, we can define a primary font directly in our _quarto.yml file:
To do so, we first need to choose and import our font(s). Start by exploring the many fonts available at https://fonts.google.com/.
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 400 and ExtraBold 800 styles, though you can choose as many fonts and styles to import as you’d like. Note: You must import a higher weight font style if you plan to use bolded text.
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.
To apply an imported font as a primary font, update _quarto.yml with the font name.
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):
// Import 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; You must import a higher font weight (e.g. 800), in addition to your standard “regular” weight, if you wish to bold text – even bolding text using markdown syntax (e.g. **this text is bold**) will not work unless a higher font weight style is imported).
In order to really fine-tune the appearance of our site, we need to dive a bit into the world of HTML and CSS.
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 (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
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.
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
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 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
Elements comprise 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.
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 .
Attributes 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 for targeted styling with CSS (e.g.
class or id attributes) – more on this soon.
You can use any text editor to write HTML, but the following steps assume you’re working in RStudio (you can continue to work on your branch in your website’s project directory).
1. In the RStudio Terminal, use the touch command (alternatively, use New Blank File > Text File in the Files pane) to create an HTML file (for simplicity, I did this in my project’s root directory), then choose Open in Editor.
2. Type or copy/paste the following into your practice-html.html file:
practice-html.html
<!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, where you can read more about <a href="https://ucsb-meds.github.io/">MEDS</a>.</p>
<p>This is very important text!</p>
</body>
</html>Click Preview to render the HTML
Quarto (.qmd) files allow us to write markdown, then Render that markdown as HTML (we can also write HTML directly in .qmd files).
1. Now, use the touch command (or New Blank File > Quarto Doc… in the Files pane) to create a new .qmd file.
2. Type or copy/paste the following into your practice-markdown.qmd file:
Click Render to render the markdown as HTML (it will render it as a web page if you’re in your website’s project directory)
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:
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, ;
Any HTML element can be used as a selector. The declarations specified apply to all HTML elements of that type.
Group multiple element selectors together (separated by commas) if you want them all styled the same way.
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.
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
HTML
Output
If you’re like me, you’ll probably find yourself using class selectors most often!
The universal selector selects all HTML elements on the page. It is written using only an asterisk, *.
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
Output
Note: You can also use the <span> tag to apply class or ID selectors to part of an element (e.g. let’s say I have a class selector, .blue-text{color: blue;}. I can target parts of HTML elements using this selector in conjunction with the <span> tag: <p>In this sentence, only the word <span class="blue-text">blue</span> is styled.</p>)
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 Selectors
Below is one solution – yours may look different!
practice-styles.css
/* ------- element selectors ------- */
/* style level one headers */
h1 {
background-color: #49bf96;
border-radius: 25px;
letter-spacing: 5px;
text-align: center;
}
/* purple italicized hyperlinks */
a {
color: purple;
font-style: italic;
}
/* ------- class selectors ------- */
/* blue text */
.blue-text {
color: blue;
}
/* large red text */
.important-text {
color: red;
font-size: 30px;
}practice-html.html
<!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>Here is my second paragraph, where you can read more about <a href="https://ucsb-meds.github.io/">MEDS</a>.</p>
<p class="important-text">This is <span class="blue-text">very</span> important text!</p>
</body>
</html>
We can write our CSS rules in styles.css, but alternatively, we can write them directly in our styles.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).
Let’s say I want to similarly style (add spacing between each letter, increase the font weight, make a dark green 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 page title, “About”
On my Resources page, I want to style the page title, “All of my favorite resources!”
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 sections, “Hi there!”, “Education” and “Experience”, are <h2> elements
My About page and Resource page titles are <h1> elements
Note: These <h1> elements also have a class, title– we’ll come back to that shortly.
Here, we have a grouping selector that targets all <h1> and <h2> elements – it increases both the spacing between each letter and it colors those text elements dark green.
No CSS styling on h1 and h2 headers
With CSS styling on h1 and h2 headers
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 <h2> elements across my site. If an element on any of my pages has either of those tags, it will get styled according to the declarations included in our CSS rule.
Earlier, we noted that the page titles (“Samantha Csik” on the landing page, “About” on the About page and “All my favorite resources!” on the Resources page), are all <h1> elements and also are given the class, title (e.g. <h1> class="title">All of my favorite resources!</h1>).
The Quarto framework has already 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 color any text elements that are assigned the class .title red:
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.
Let’s write a couple of other elements that are not assigned the title class to see what happens. I’ll do this on my About page:
about.qmd
---
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>
Class selectors allow us to customize exactly how CSS rules apply to particular elements. In this example, only <h1> elements that are assigned the class, title, are colored red. Any <h1> elements that are not assigned the class, title, are styled according to our h1, h2 {} element selector.
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.
Let’s first create two different classes: one to center text on the page, and another to color text orange. Then, we’ll add elements to our Resources page to test out our new class selectors:
Here, I’m creating three paragraphs – (1) a paragraph that is assigned just the .orange-text class, (2) a paragraph that is assigned just the .center-text class, and (3) a paragraph has no classes.
What happens if you create your custom subtitle using an <h1> tag instead of <p>? Why do you think this happens?
Class selectors take the form .selector-name {}
Unlike element selectors, class selectors must be applied to the elements that we want to style, e.g. <h1 class="selector-name">Content</h1>
Using the same element selectors as in our previous example:
Let’s add a couple more paragraphs to try out using more than one class selector on a particular element:
resources.qmd
---
title: "All my favorite resources!"
---
<p class="orange-text">This paragraph is orange.</p>
<p class="center-text">This paragraph is centered.</p>
<p>This paragraph has no styling.</p>
<p class="center-text orange-text">This paragraph is centered and orange.</p>
<p class="orange-text">**This paragraph is orange and bolded using markdown syntax, though you can also write and apply a selector to bold text.**</p>
HTML elements can have more than one class, e.g. <p class="class1 class2 class3 etc">
I tend to use a mix of both approaches (HTML & Quarto syntax). For example:
resources.qmd
---
title: "All my favorite resources!"
---
<p class="orange-text">Here is some orange text.</p>
<p>And here is some normal text beneath it.</p>
[Here is more orange text written using Quarto's syntax]{.orange-text}
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.
You’ll notice the []{} and ::: {} ::: 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!
^ How I feel most of the time while trying to write CSS
For me, it’s a lot of it is trial and error. Inspecting your website can take patience and persistence to figure out how exactly to target your desired element. Some things that have helped me:
- re-rendering often to ensure your Sass/CSS is working as expected
- Google! (lots of queries that look like, “CSS underline text”, “CSS rounded corners”, etc.)
- W3 Schools – seriously such a valuable resource (especially their interactive tutorials)
- drawing inspiration (and borrowing source code) from other webpages
Play around with selectors and update declaration values (or add/remove declarations) while inspecting your website. This allows you to try out styles before actually hard-coding them, and also helps you identify exactly which elements different selectors are manipulating. It can sometimes take a little digging in the Inspect pane to find what you’re looking for. Note that these changes are only temporary – refreshing your web browser will revert your site back to its original state.
W3Schools has tons of great examples and interactive tutorials for learning CSS. Touching (and breaking) code is one of the best ways to learn!
This is a Quarto Presentation. To learn more, visit https://quarto.org.
If you see mistakes or want to suggest changes, please create an issue on the source repository.