Customizing Your Personal Website Using CSS (and some other stuff)

class: inverse, middle

# Customizing Your Personal Website Using CSS <svg aria-label="Alternate CSS3 Logo" role="img" viewBox="0 0 384 512" style="height:1em;width:0.75em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:#93C6C2;overflow:visible;position:relative;"><title>Alternate CSS3 Logo</title><path d="M0 32l34.9 395.8L192 480l157.1-52.2L384 32H0zm313.1 80l-4.8 47.3L193 208.6l-.3.1h111.5l-12.8 146.6-98.2 28.7-98.8-29.2-6.4-73.9h48.9l3.2 38.3 52.6 13.3 54.7-15.4 3.7-61.6-166.3-.5v-.1l-.2.1-3.6-46.3L193.1 162l6.5-2.7H76.7L70.9 112h242.2z"/></svg> (and some other stuff)

Sam Csik | Data Training Coordinator

National Center for Ecological Analysis & Synthesis

Masters of Environmental Data Science | Summer 2021

Slides & source code available on [<svg aria-label="GitHub" role="img" viewBox="0 0 496 512" style="height:1em;width:0.97em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:#93C6C2;overflow:visible;position:relative;"><title>GitHub</title><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>](https://github.com/UCSB-MEDS/customizing-websites-css)

---
### Prerequisites

You should already have a `{distill}` website (or at least the bones of one) deployed using github pages. Importantly, this website should also have *some* content (e.g. text, headings, etc.) for us to customize.

If you first need to get your website up and running, follow along with these [step-by-step instructions](https://docs.google.com/document/d/1c0SZiVvp32UTJ9sK_yVjI8ou6pVdFRXsY2236tiTA1c/edit) by Allison Horst before moving forward.

---
### So you've created your personal website using `{distill}`...

[`{distill}`](https://rstudio.github.io/distill/) gives us with an easy-to-use web publishing format to create our personal websites. A massive benefit is that these websites already look pretty slick right out of the box.

.center[
<img src="img/sam_distill.png" width="70%" />
]

---
### But without some additional modifications, it can be challenging to make *your* website stand out from the rest.

.center[
<img src="img/unique.gif" width="55%" />
]

In order to make those changes, we need to dive a bit into the world of **CSS**. Some of you may have already heard of and/or used 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 `{distill}` 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.

**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.

.center[
<img src="img/html_css_lego.jpeg" width="35%" />
]

.center[
Source: Nicolas Karasiak, [GitHub: nkaraskiak/Illustration](https://github.com/nkarasiak/Illustration/tree/master/LegoJavascript)
]

.footnote[
1 **[Markdown](https://www.markdownguide.org/)** and **[R Markdown](https://rmarkdown.rstudio.com/)** 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.
]

---
### Your browser has its own internal style sheet to render HTML

.center[
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.
]

.pull-left[
<img src="img/website_html.png" width="100%" />
.center[
HTML
]
]

.pull-right[
<img src="img/website_basic_styling.png" width="100%" />
.center[
Browser default styling
]
]

---
### CSS adds **pizzazz** to web page renderings

.center[
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).
]

.pull-left[
<img src="img/website_basic_styling.png" width="100%" />
.center[
Browser default styling
]
]

.pull-right[
<img src="img/website_with_css.png" width="100%" />
.center[
CSS styling
]
]

---
### A *light* introduction to HTML - elements

HTML consists of a series of **elements**, comprised of **opening tags** and **closing tags** that render some form of content in a particular way.

.center[
**The basic anatomy of an HTML element:**
]

.center[
<img src="img/element.png" width="60%" />
]

.footnote[
In R Markdown syntax: `# Welcome to your first MEDS mini-workshop`

Source: [“Getting Started with HTML - Learn Web DEVELOPMENT: MDN.” Learn Web Development | MDN, developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Getting_started.](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Getting_started) 
]

---
### A *light* introduction to HTML - nested elements

You can also *nest* elements. Remember to close out tags from the inside-out to avoid unexpected renderings.

.center[
**Nested HTML elements:**
]
.center[
<img src="img/nested_elements.png" width="60%" />
]

.footnote[
In R Markdown syntax: `# Welcome to your first **MEDS** mini-workshop`

---
### A *light* introduction to HTML - attributes

HTML elements can also have **attributes** which contain extra information about the element that will not be rendered as visual content1 on the web page. 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 will come back to this concept in a little bit.

.center[
**The basic anatomy of an attribute:**
]

.center[
<img src="img/attribute.png" width="65%" />
]

.footnote[
1One example that you may already be familiar with is **alt text**. While you add alt text to the top of code chunks, knitting your `.Rmd` will actually add that text as an attribute on the visual content you generate (e.g. a `ggplot`) -- you cannot see it rendered on the screen, but screen readers can find it by searching for any content with the `alt` attribute to read aloud for visually impaired users.

Source: [Getting Started with HTML, mdn web docs](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Getting_started) 
]

---
### Some commonly used html elements

* `<div></div>`: group common elements
* `<img></img>`: present an image
* `<h1></h1>`: creates a first-level heading (largest)
* `<h6></h6>`: creates a sixth-level (smallest)
* ``: begins a new paragraph
* ` `: adds a line break
* ``: bolded text
* ``: italicized text
* `<a></a>`: anchors (i.e. links) an HTML page to another page 
 * e.g. `<a href="https://ucsb-meds.github.io/">text_I_want_to_hyperlink</a>`
* ``: an inline container used to markup part of a text or document
 * e.g. `My favorite color is green.`

---
### A *light* introduction to CSS

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 first-level (`<h1>`) headings to be large green text"* could be coded as:

.pull-left[
<img src="img/CSS_syntax.png" width="100%" />
]

.pull-right[
* **Selectors** define a condition to match HTML elements *(e.g. first-level 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 that property *(e.g. green)*
* A property and its corresponding value are separated by a colon, `:`. Declarations end with a semicolon, `;`
]

.footnote[
Source: [“What Is CSS? - Learn Web Development: MDN.” Learn Web Development | MDN, developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/What_is_CSS.](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/What_is_CSS) 
]

---
### "Inspect"ing web pages allows you to view and edit HTML & CSS source code

*Don't worry -- any edits you make are only visible to you and will disappear when you refresh the web page!* Using the "Inspect" tool is a great way to get a better sense of how CSS is used to modify particular HTML elements.

Navigate to any web page and *right click* on an element of interest (e.g. text, images, links, etc.) and choose *Inspect* to pull up the underlying HTML & CSS files. Here, I am going to inspect the dark blue banner along the top of my `{distill}` website.

.center[
<img src="img/distill_banner_inspect1.png" width="50%" />
]

---
### An "Inspect" roadmap

.center[
<img src="img/distill_banner_inspect2.png" width="80%" />
]

---
### Make some edits to a web page's style by altering declaration values

.center[
<img src="img/distill_banner_inspect3.png" width="80%" />
]

---
### Check out your web page with its "edited" CSS!

.center[
<img src="img/distill_banner_inspect4.png" width="80%" />
]

.center[
*Refreshing the web page will revert any changes you made.*
]
---
### Okay that was like...

.center[
<img src="img/magic.gif" width="50%" />
]

.center[
But what's even *more* magical is how easy `{distill}` makes it to actually customize parts of your site's appearance using CSS.
]

---
### Start by making sure you have a CSS file in your web page repo's root directory

If you do not already have a `.css` file, you can generate one by running the `distill::create_theme()` function in your console as follows:

```r
# the `name` argument sets the name of the theme file, e.g. `theme.css`
# the `edit` argument opens an editor (in RStudio) for the theme file

distill::create_theme(name = "theme", edit = TRUE)
```

This function creates a file named `theme` with the file extension `.css`. Here is where you will define CSS custom properties and/or edit existing default values. You'll notice that there are a series of CSS rules, that should look similar to the example shown earlier ([slide 12](https://ucsb-meds.github.io/customizing-websites-css/#12)). They take the format:

```r
scope { # think of 'scope' as the 'selector'
  --some-property:       some-value; # e.g. --code-size:    50px;
  --another-property:    another-value; # e.g.  --title-color:   #333CFF;
}
```

.footnote[
This content has been adapted from the `{distill}` document on theming. This is a *great* resource for getting started on web page customization. You can find that document [here](https://rstudio.github.io/distill/website.html#theming).
]

---
### The 'out-of-the-box' `theme.css` file

.center[
<img src="img/theme_file.png" width="90%" />
]

---
### Apply your theme to your `{distill}` website

Add a theme key to the top-level of your `_site.yaml` configuration file along with the name of your `.css` file (e.g. mine is named `theme.css`). For example:

```r
name: "samanthacsik.github.io"
title: "Samantha Csik"
*theme: theme.css
description: |
  Samantha Csik
output_dir: "docs"
navbar:
  right:
    - text: "Home"
      href: index.html
    - text: "Publications"
      href: publications.html
    - text: "Posts"
      href: posts.html
    - text: "Projects"
      href: projects.html
    - text: "Teaching"
      href: teaching.html
    - text: "Curriculum Vitae"
      href: CV.html
output: distill::distill_article
```

---
### So where do we start styling??

.center[
<img src="img/mind_blown.png" width="45%" />
]

---
### Import custom Google Fonts at the top of your `theme.css` file

**Steps for applying custom Google fonts:**

**1.** explore Google font styles [here](https://fonts.google.com/) (there are *many* to choose from)</span<>

**2.** embed the font(s) at the top of your `theme.css` file using the [@import](https://developer.mozilla.org/en-US/docs/Web/CSS/@import) method1 where prompted (i.e. **before** any rules are specified). Below, I'm importing the fonts, **Caveat** and **Montserrat**.

**3.** specify your imported font style as values on the appropriate property types (*continued on next slide*)

```css
/* Optional: embed custom fonts here with `@import`          */
/* This must remain at the top of this file.                 */
@import url('https://fonts.googleapis.com/css2?family=Caveat');
@import url('https://fonts.googleapis.com/css2?family=Montserrat');
```

.footnote[
1The Google fonts website will generate the `@import` code for your chosen font. Choose a font family and select a particular style. Click on the *Selected families* icon in the upper right hand corner and choose the `@import` radio button under *Use on the web*. Copy and paste the code into your CSS file.
]

---
### Change default font styles to any of your imported fonts

```css
html {
  /*-- Main font sizes --*/
  --title-size:      50px;
  --body-size:       1.06rem;
  --code-size:       14px;
  --aside-size:      12px;
  --fig-cap-size:    13px;
  /*-- Main font colors --*/
  --title-color:     #000000; 
  --header-color:    rgba(0, 0, 0, 0.8);
  --body-color:      rgba(0, 0, 0, 0.8);
  --aside-color:     rgba(0, 0, 0, 0.6);
  --fig-cap-color:   rgba(0, 0, 0, 0.6);
  /*-- Specify custom fonts ~~~ must be imported above   --*/
*  --heading-font:    Montserrat; /* default = sans-serif */
*  --mono-font:       monospace;
*  --body-font:       Caveat; /* default = sans-serif */
*  --navbar-font:     sans-serif;  /* websites + blogs only */
}
```

---
### Change default font colors by altering hex color codes1 or adjusting `rbga()` values2

```css
html {
  /*-- Main font sizes --*/
  --title-size:      50px;
  --body-size:       1.06rem;
  --code-size:       14px;
  --aside-size:      12px;
  --fig-cap-size:    13px;
  /*-- Main font colors --*/
*  --title-color:     #000000;
*  --header-color:    rgba(0, 0, 0, 0.8);
*  --body-color:      rgba(0, 0, 0, 0.8);
*  --aside-color:     rgba(0, 0, 0, 0.6);
*  --fig-cap-color:   rgba(0, 0, 0, 0.6);
  /*-- Specify custom fonts ~~~ must be imported above   --*/
  --heading-font:    sans-serif;
  --mono-font:       monospace;
  --body-font:       sans-serif;
  --navbar-font:     sans-serif;  /* websites + blogs only */
}
```

.footnote[
1Generate Hex color codes using the [HTML color picker](https://htmlcolorcodes.com/color-picker/), or install the [Colorpick Eyedropper Chrome Extention](https://chrome.google.com/webstore/detail/colorpick-eyedropper/ohcpnigalekghcmgcdcenkpelffpdolg?hl=en), which allows you to select color values directly from web pages.

2A note on `rgba(red, green, blue, alpha)`: the `red` argument, for example, defines the intensity of red between 0-255 or a % value between 0-100%; the `alpha` argument defines opacity as a number between 0.0 (fully transparent) and 1.0 (fully opaque). You can convert any Hex color code to `RBG` values using an online [converter](https://www.rapidtables.com/convert/color/hex-to-rgb.html).
]

---
### Change default font sizes

```css
html {
  /*-- Main font sizes --*/
*  --title-size:      50px;
*  --body-size:       1.06rem;
*  --code-size:       14px;
*  --aside-size:      12px;
*  --fig-cap-size:    13px;
  /*-- Main font colors --*/
  --title-color:     #000000;}}
  --header-color:    rgba(0, 0, 0, 0.8);
  --body-color:      rgba(0, 0, 0, 0.8);
  --aside-color:     rgba(0, 0, 0, 0.6);
  --fig-cap-color:   rgba(0, 0, 0, 0.6);
  /*-- Specify custom fonts ~~~ must be imported above   --*/
  --heading-font:    sans-serif;
  --mono-font:       monospace;
  --body-font:       sans-serif;
  --navbar-font:     sans-serif;  /* websites + blogs only */
}
```

.footnote[
**Pixels** (`px`) are relative to screen size. For low-dpi (Dots Per Inch) devices, 1px is one device pixel of the display. For high resolution screens, 1px implies multiple device pixels.
]
---
### Defining your own CSS rules may require some "Inspect"ing

Creating custom CSS rules for your web site requires some sleuthing (similar to what we did while "Inspecting" our web page) and an understanding of how to apply [CSS selectors](https://www.w3schools.com/cssref/css_selectors.asp).

For example, say I want to change the color of the headings, *Biography*, *Education*, and *Experience* on my landing page to pink (hex code #C41A60). *Inspecting* these headings reveals that they are all `<h3>` elements.

.pull-left[
<img src="img/landing_page.png" width="100%" />
]

.pull-right[
<img src="img/h3.png" width="100%" />
]

---
### Construct custom CSS rules that target groups of elements

Following the [CSS selectors](https://www.w3schools.com/cssref/css_selectors.asp) guide, we can construct a custom CSS rule that will color any `<h3>` element on our website pink:

```css
/*-- Additional custom styles --*/
/* Add any additional CSS rules below */
  
h3 {
  color: #C41A60; 
}
```

.center[
<img src="img/pink_h3.png" width="60%" />
]

---
### "Cheat" code: you can use *inline* style directly in your `.Rmd` to alter the appearence of web page content

For example, you can use the `` tag styled with CSS to update text in your `.Rmd` file.

`MA in Ecology, Evolution & Marine Biology, 
2020` will render as:

.center[
<img src="img/red2020.png" width="70%" />
]

---
### Get inspired by sites on the [distillery](https://distillery.rbind.io/) and borrow open source code

.center[
<iframe src="https://distillery.rbind.io/" width="70%" height="400px" data-external="1"></iframe>
]

.footnote[
One of the more challenging parts of creating custom CSS rules (for newbies like myself) is knowing what **selectors** to use and what is design patterns are even possible. Looking at (and borrowing) source code for other `{distill}` sites can help jump start your own custom CSS styling.
]

---
### Let's try borrowing some code

I came across [Jenna Eagleson's web site](https://jeagleso.github.io/website/) on the [Distillery Showcase](https://distillery.rbind.io/showcase.html) and loved the way her headings appear. You can check out all of her custom CSS rules at the bottom of her website's [theme.css file](https://github.com/jeagleso/website/blob/main/theme.css).

.pull-left[
<img src="img/JEagleson.png" width="100%" />
]

.pull-right[
<img src="img/JEagleson_theme.png" width="100%" />
]

---
### Adapting custom CSS rules for your own website

I see a rule which styles any `h1` - `h6` heading elements with a particular font-weight, color, and spacing between letters.

```css
h1, h2, h3, h4, h5, h6 {
  letter-spacing: 2px;
  font-weight: 300;
  color: #3D5A80;
}
```

I just want to apply the letter-spacing and font-weight styles to my headings, so I'll borrow those declarations and omit the color declaration. I'm also going to increase the letter-spacing style from `2px` to `5px`:

```css
h1, h2, h3, h4, h5, h6 {
  letter-spacing: 5px;
  font-weight: 300;
}
```

---
### Voila!

.pull-left[
<img src="img/half_edit.png" width="100%" />
.center[
Without letter spacing</span?
]
]

.pull-right[
<img src="img/full_edit.png" width="100%" />
.center[
With letter spacing
]
]

---
class: inverse, center, middle

### The "other stuff"

---
### Adding a footer to your website

There are a variety of ways to add a footer (the section of content typically included at the bottom of web pages) to your web page. Ultimately, you'll need to add a `_footer.html` file to the root directory of your `distill` site repository. These are the steps I followed:

**1.** Choose `New File -> R HTML` 
**2.** Delete all auto-filled content (lines 1-22) 
**3.** Save and name `_footer.html` (a popup box will ask if you'd like to use the standard extension ".Rhtml" or ".html" -- choose "Use .html") 
**4.** Add content using HTML markup, save, and knit 
**5.** Build your site to see you footer!

One great example is the [MEDS Website](https://ucsb-meds.github.io/). The code used to generate that footer is as follows:

```html

<a href="https://bren.ucsb.edu/"><img src="img/bren_white_logo.png" alt="Bren School logo" style="width:350px;" /></a>

This website was made with <a href="https://rstudio.github.io/distill/">distill by RStudio</a>, and with inspiration from the <a href="https://ubc-mds.github.io/">UBC Master of Data Science website</a>.

```

---
### Add your CV to your website

There are a few ways to include your resume/CV on your website (aside from translating all your CV content into your `Rmd` using R Markdown syntax).

**1.** Add a link for visitors to download your CV.pdf (e.g. `[Download my CV here](file/path/to/my/cv.pdf)` renders as [Download my CV here](img/cv_example.pdf))

**2.** Hyperlink your CV.pdf to a navbar tab in `_site.yml` -- when you click on that tab, it takes you directy to a pdf viewer

```r
navbar:
  right:
    - text: "Home"
      href: index.html
    - text: "CV"
      href: path/to/my/cv.pdf
```

**3.** Add a scrollable plugin to render your pdf directly on-screen using the function

```r
knitr::include_graphics("file/path/to/my/cv.pdf")
```

---
### Additional Resources

* [rstudio4edu Chapter 25: Make it fancier](https://rstudio4edu.github.io/rstudio4edu-book/distill-fancy.html)
* [The Mockup Blog: Building a blog with distill](https://themockup.blog/posts/2020-08-01-building-a-blog-with-distill/ ) 
* [Package 'distill' documentation](https://cran.r-project.org/web/packages/distill/distill.pdf)
* [jhelvy.com: Customizing distill with {htmltools} and CSS](https://www.jhelvy.com/posts/2021-03-25-customizing-distill-with-htmltools-and-css/)

---
class: center, middle

### Now get to customizing!

Slides created via the R packages:

[**xaringan**](https://github.com/yihui/xaringan) 
[**gadenbuie/xaringanthemer**](https://github.com/gadenbuie/xaringanthemer)