06 - Websites

Building with Quarto

Websites

  • Websites are essentially format: html + a Quarto Project
  • Website is different than format: html in that it has multiple pages
  • Website is our first exploration into Quarto Projects
  • Website/book are very similar in that they associate multiple pages/resources into a connected resource

Why not WordPress, Tumblr, Medium.com, Blogger.com, etc?1

  • No R Markdown support (even math support is often nonexistent or awkward)

  • Huge benefits of static websites compared to dynamic websites

  • all static files, no PHP or databases, no login/password, work everywhere (even offline)

  • typically fast to visit (no computation needed on the server side), and easy to speed up via CDN

Personal blog:

Limited and gated at Medium.com

https://medium.com/towards-data-science/a-gentle-guide-to-statistics-in-r-ccb91cc1177e

vs

Full control at on my own page

https://themockup.blog/posts/2018-12-10-a-gentle-guide-to-tidy-statistics-in-r/

Create a website

quarto create-project MySiteName --type website

Create a blog

quarto create-project MyBlogName --type website:blog

RStudio > New Project > New Quarto Blog

Creating a blog

$ quarto create-project MyBlogName --type website:blog

Creating project at myblog:
  - Created _quarto.yml
  - Created index.qmd
  - Created posts/welcome/index.qmd
  - Created posts/post-with-code/index.qmd
  - Created about.qmd
  - Created styles.css
  - Created posts/_metadata.yml

Create a blog

  • A blog is a website with specific “opinions” already made
  • Includes a listing automatically from posts directory
  • Can build custom listings in several ways

Core blog workflow

  • Create a new folder under /posts - this folder will be the “slug” URL (like themockup.blog/2022-07-25-new-post/)
  • Create a new index.qmd within the new folder

Your Turn

  • Create a new RStudio project (in a separate RStudio session) and select Quarto blog
  • Give it a name
  • Explore the directory

Rendering posts

  • On a specific post, Render with RStudio > Render
  • Build tab > Render/Preview Website

These will preview the entire website

  • Render via termianl with quarto render on a specific post - this will just render that specific post

When you render the website, it will re-execute code in older posts. Not ideal in many situations!

Your Turn

  • Let’s render the index.qmd together!
  • Now, let’s try Build > Render Website

Freeze

You can use the freeze option to denote that computational documents should never be re-rendered during a global project render, or alternatively only be re-rendered when their source file changes

execute:
  freeze: true  # never re-render during project render
execute:
  freeze: auto  # re-render only when source changes

freeze: true is typically added to a _metadata.yml file within a specific directory, affecting all files in that directory.

In the case of a blog - the _metadata.yml is saved at the root of the posts directory. You can have it only within specific subdirectories for more complex sites.

Cache

Cache on the other hand, stores the results of computations for a specific file.

Note that cache invalidation is triggered by changes in chunk source code (or other cache attributes you’ve defined).

execute:
  cache: true

I typically use cache throughout various types of outputs when I have computationally expensive chunks. Think a tidymodels workshop website that is demo’ing with grid-tuning.

Your Turn

  • Add a _metadata.yml to the /posts/ directory

  • Add the freeze code to _metadata.yml

execute: 
  freeze: true

  • Render index.qmd in the project directory and note the items that are built

  • Explore the _freeze directory

  • Marvel at the “beautiful” JSON - it’s not for you, it’s for the machine

Themes

https://quarto.org/docs/websites/website-blog.html#themes

default, cerulean, cosmo, cyborg, darkly, flatly, journal, litera, lumen, lux, materia, minty, morph, pulse, quartz, sandstone, simplex, sketchy, slate, solar, spacelab, superhero, united, vapor, yeti, zephyr

To change theme, modify the bottom of your website’s _quarto.yml

format:
  html:
    theme: cosmo

Themes

Your Turn

  • Open _quarto.yml and change the theme to one of the support Bootswatch themes
  • Create a new folder in /posts/ - title it 2022-07-26-my-first-post
  • Create a new blank index.qmd in that folder, add a format: html YAML header
  • Add some text and a markdown image: ![](), along with maybe some code :laptop:
  • Render it!

Adding an About page

---yaml
twitter-card:
  image: images/profile-preview.png
  creator: "@thomas_mock"
open-graph: true
title: "Tom Mock"
image: images/profile-preview.png
about:
  template: trestles
  links:
    - icon: twitter
      text: Twitter
      href: https://twitter.com/thomasmock
    - icon: github
      text: Github
      href: https://github.com/jthomasmock
---

About page templates

about:
  template: trestles

Your Turn

  • Open your about page (about.qmd)
  • Change some of the details, add more details and choose a specific template (jolla, trestles, solana, marquee, broadside)
  • Render it!

Landing page

  • The landing page for your website defaults to the blog/listings page
  • your-proj/index.qmd becomes your “home page”
  • blogdown users might be used to/prefer your landing page being your “about me” page
  • This is easy to do with renaming your index.qmd -> blog.qmd and about.qmd -> index.qmd
  • Re-structuring your website also requires modifying your _quarto.yml
website:
  title: "My blog name"
  site-url: "https://MyBlogSiteUrl.com"
  navbar:
    right:
     - blog.qmd
     - icon: twitter
       href: "https://twitter.com/my_user_name"

Example: https://www.ericekholm.com/posts/demo-quarto-site/

Listings

Listings

Type Description
default A blog style list of items.
table A table of listings.
grid A grid of listing cards.

Listings

By default, listings will appear in full width rows that display the item’s metadata (author and date), title, description, and image.

Grid style listings display a card for each item.

The table listing style provides a traditional tabular layout.

Your Turn

  • Open your existing Quarto blog from before
  • Let’s change the listing type of our blog - change from default to grid
  • Re-render the index.qmd

Listing location

---
title: "Listing Example"
listing:
  id: sample-listings
  contents: posts
  type: table
---

You can review the following documents for additional information:

::: {#sample-listings}
:::

Populating listings

---
title: "Listing Example"
listing:
  contents: posts
---
title: "Listing Example"
listing:
  - id: lab-reports
    contents: "reports/*.qmd"
    type: grid
  - id: lab-notes
    contents: "lab-notes/*reports.qmd"
    type: table
Some stuff

::: {#lab-reports}
:::

Some other stuff

::: {#lab-notes}
:::

Manual listings

Sometimes you might want to build out your own listing and link to arbitrary content rather than specific rendered file.qmd

---
listing:
  contents:
    - author: First Author
      title: [First Title](a-url.com)
    - author: Second Author
      title: [Second Title](a-url2.com)
---
---
listing:
  contents:
    - items.yml
---
- author: Tom Mock
  title: <a href='quarto.org'>An intro to Quarto</a>
- Author: Katie Masiello
  title: <a href='pins.rstudio.com'>Intro to pins</a>

Complex Example:

Complex Example, index.qmd YAML

listing: 
  - id: etl
    contents: "etl.yml"
    type: grid
    grid-columns: 2
    image-height: 100px
  - id: modeling
    contents: "modeling.yml"
    type: grid
    image-height: 100px
    grid-columns: 2
  - id: pins
    contents: "pins.yml"
    type: table
    field-display-names: 
      subtitle: "Description"
      date-modified: "Last Updated"
  - id: api
    contents: "api.yml"
    type: default
    image-align: left
    image-height: 75px
  - id: apps
    contents: "apps.yml"
    type: default
    image-align: left
    image-height: 75px
---

Publishing

Destination Description
GitHub Pages Publish content based on source code managed within a GitHub repository. Use GitHub Pages when the source code for your document or site is hosted on GitHub.
RStudio Connect Publishing platform for secure sharing of data products within an organization. Use RStudio Connect when you want to publish content within an organization rather than on the public internet.
Netlify Professional web publishing platform. Use Netlify when you want support for custom domains, authentication, previewing branches, and other more advanced capabilities.
Other Services Content rendered with Quarto uses standard formats (HTML, PDFs, MS Word, etc.) that can be published anywhere. Use this if one of the methods above don’t meet your requirements.

Publishing

Static Only

  • quarto CLI: quarto publish DESTINATION DOCUMENT.QMD
  • quarto R package: quarto::quarto_publish_???()

Code

  • Evaluate R/Python code and render on a schedule

  • RStudio Connect

  • rsconnect::deployDoc(quarto = "path/to/quarto")

    • rsconnect::deployDoc(quarto = quarto::quarto_path())

Static Publish

  • quarto::quarto_publish_???()

    • quarto_publish_site(server = "rstudioconnect.example.com")
    • quarto_publish_doc(server = "rpubs.com")
    • quarto_publish_app(server = "shinyapps.io")

  • quarto publish DESTINATION DOCUMENT.QMD

    • quarto publish netlify document.qmd
    • quarto publish gh-pages document.qmd
    • quarto publish connect document.qmd

Netlify

  • Cheat code: Netlify drop

GitHub Pages

{=html, echo=FALSE} <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

  • Name your content index.qmd to generate index.html -> Push to GitHub

Your Turn

In your blog project:

quarto publish quarto-pub
  • Choose a username and/or authenticate with quartopub.com
  • Enjoy your new blog/site!

Websites

Similar to blog, but less of a focus on listing/posts and more focus on individual pages and overall navigation.

Quarto Project

When you create a project, a _quarto.yml config file is created. Here is an example of what the _quarto.yml looks like:

project:
  output-dir: _output

toc: true
number-sections: true
bibliography: references.bib  
  
format: #< default format inherited by other documents
  html:
    css: styles.css

More complex example

Quarto Projects

  • Minimal project has at least 1x file and 1x _quarto.yml
  • A project is a directory (and can have sub-directories)

A typical project is used to:

  • Aggregate content (website/blog/book)
  • Share metadata (YAML config) across multiple files
  • Render an entire directory together or redirect output to another directory
  • Freeze computation across a project or team

Books

The structure of a Quarto book can be as simple as a list of chapters, or can alternatively incorporate multiple parts and/or appendices. Quarto book chapters and sections are automatically numbered (for cross-referencing), however you can also specify that some parts of the book should remain unnumbered.

Book structure

project:
  type: book
book:
  title: "mybook"
  author: "Jane Doe"
  date: "8/18/2021"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd
bibliography: references.bib
format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreport
  epub:
    cover-image: cover.png

Book crossrefs

Quarto cross references provide automatic numbering and reference creation for figures, tables, equations, sections, listings, theorems, and proofs. In books, cross references work the same way except they can reach across chapters.

See @fig-penginus-by-island for a breakdown by island.
# Introduction {#section-intro}

or: See @sec-introduction for additional discussion.

Get started with Quarto