An Introduction to {distill} for websites

workshop free

How you too can learn to {distill}.

~
2021-03-19

Want to learn how to build a website using {distill}? This is a short blog post explaining the basics of Distill.

https://github.com/laderast/distill_website/

Workshop Video

Learning Objectives

Before You Start

  1. Install R/RStudio Desktop to your Computer.
  2. Install the following packages in R:
install.packages(c("tidyverse", "postcards", "distill", "usethis"))
  1. Create a website project in your home directory using usethis.
usethis::use_course(url="laderast/distill_website",destdir=".")
  1. Take a look at the website before we get started:

https://distill-example.netlify.app/

  1. Gather up the follwing materials:
  1. Sign up for a netlify account and log in: https://netlify.com

Taking a tour of the Project

These are the main files for the project.

How does {distill} work?

{distill} is what is called a static site generator. It takes Markdown and Rmarkdown and converts them to . .html files.

Much like any RMarkdown file, {distill} uses {knitr} and pandoc to build your website files that are contained in an RStudio Project. It knits your .Rmd files, converting them to .html files to a folder. The default name of this folder is called _site and it contains all of them files you need to upload to make a website.

What is Netlify?

Netlify is what is called a hosting service. This is a network of computers called web servers that are accessible via web addresses that will serve your website files when they are requested by a web browser.

The amazing thing about Netlify is that it is mostly free and it is very fast, no matter where you are (they have web servers almost everywhere).

We’ll use Netlify Drop to get our website files up and accessible as quickly as possible.

Customize your about links

Take a look at about.Rmd and start filling out the front matter with your own links:

links:
  - label: LinkedIn
    url: "https://www.linkedin.com/in/ted-laderas-0714a92/"
  - label: Twitter
    url: "https://twitter.com/tladeras"
  - label: Portfolio
    url: "index.html"
  - label: Email
    url: "mailto:email@email.com"

Adding a photo

Add your photo to the images folder. Change the line in about.Rmd:

image: "image/ted.jpg"

to the name of your file. For example, if your file is named jane.jpg and you put it in images:

image: "image/jane.jpg"

Building your website using the Build Tab

In the top right panel in RStudio (next to Environment and History), there is a “Build” Tab.

Press the Build Website to run knitr, which will knit your website to the _site folder. This is where your rendered content lives.

Build Website Tab

Previewing your website

Try out different postcards themes

The postcards package has the following built in themes:

Change this line in your about.Rmd file to the theme of your interest and start building again:

output:
  postcards::trestles

Add Your Rendered .html files to the articles/ folder

You can now add your articles to the articles/ folder.

There are a couple example articles here. Add your own files here.

In general, you’ll put knitted html articles here. Distill does not rebuild articles, it leaves that up to you.

The relative path to access articles is like this:

articles/crops.html

You’ll use this when adding links to your menu.

Customize the Menu

The menu lives in the _site.yml file:

navbar:
  right:
    - text: "Home"
      href: index.html
    - text: "About"
      href: about.html
    - text: "Articles"
      menu:
          -  text: "dplyr::slice()"
             href: articles/slice.html
          -  text: "Crop Yields"
             href: articles/crops.html

Add another menu entry under articles, or modify the above entries to have a link to your articles.

Build your website again and preview it to make sure the links work.

Getting Your Website Online

We’ll take the _site folder with our generated website and drop this entire folder into Netlify Drop.

https://drop.netlify.com

Updating Your Website

The first thing you want to do is claim your site and register for a Netlify account. That ties your newly created website to your account so you can update it.

When you update your website with the Build Website button, you’ll drag the _site folder onto the deploy zone. This is under the deploy tab:

More info here: https://docs.netlify.com/site-deploys/create-deploys/#drag-and-drop

Customize Your Domain

That crazy name is the address of your site. To change it, you can click on the Domain Settings button:

Domain Settings Button

In the following page, click the Options >> Edit Site Name button. You can change the first part of the domain, such as "myportfolio.netlify.app).

Edit Site Name Button

Styling your website

Note that this only applies to the main distill website and not the about.html, since that is styled separately.

In _site.yml, try uncommenting this line and seeing how the site changes.

#theme: theme.css

You can modify the appearance of your website by altering the theme.css file. Much more info about this here:

https://rstudio.github.io/distill/website.html#theming

Creating New Websites

If you want to start from scratch, I highly recommend the Distill tutorial here:

https://rstudio.github.io/distill/website.html

You may want to setup your webpage as a blog, which lets you add posts by date:

https://rstudio.github.io/distill/blog.html

Putting your site code on GitHub

This is beyond the scope of this tutorial, but you can put your site code up on GitHub as well. This has the following advantages:

If you’re interested in this, I really recommend Happy Git with R as a way to get started.

Acknowledgements

Thank you to RStudio for the {distill} package. It is so great!

Portions of this tutorial are adapted from: https://rstudio.github.io/distill/website.html and from https://rstudio.com/resources/webinars/sharing-on-short-notice-how-to-get-your-materials-online-with-r-markdown/