Basic structure

1 Introduction to RStudio

TODO

2 Introduce to Quarto websites

We’ll be creating a Quarto website, but it’s worth knowing that Quarto can produce many things. See the Quarto documentation for examples - options include:

  • Presentations
  • Dashboards
  • Manuscripts
  • Documents
  • Books

A simple website project just needs two key files:

  1. _quarto.yml
  2. index.qmd

2.1 _quarto.yml

This is file defines your project settings and website structure.

TODO: Add explanation. A yml file is YAML. plain text format. uses key-value pairs to store settings. YAML (“YAML Ain’t Markup Language”) is a simple format using key–value pairs, like:

Below is an example from quarto-template. Hover over each line to see an explanation:

1project:
  type: website

website:
2  title: "Quarto Template"
3  favicon: images/exeter.png
4  navbar:
5    right:
      - icon: github
        text: GitHub
        href: https://github.com/pythonhealthdatascience/quarto-template/
6  sidebar:
7    - logo: images/exeter.png
8      contents:
        - text: Overview
          href: index.qmd
        - pages/TODO.qmd
1
Website: Defines that this project builds as a website.
2
Website title: Appears in broswer tab and navbar.
3
Favicon: The small icon shown on the tab (often a logo).
4
Navbar: The navigation bar across the top of your site.
5
GitHub link: Adds a GitHub icon on the right side of the navbar linking to the repository (which contains the source files for the site).
6
Sidebar: Displays navigation links down the left-hand side.
7
Logo: The image shown at the top of the sidebar.
8
Sidebar contents: Lists website pages. Will list using page titles by default, but can override with text (title to use) and href (path to file).

A Quarto book is basically a website with chapter-style navigation. Under the hood, it’s still a Quarto website - just organised a little differently.

See the books guide for more information.

Example:

project:
  type: book

book:
  title: "Quarto Template"
  favicon: images/exeter.png
  chapters:
    - text: Overview
      href: index.qmd
    - pages/TODO.qmd
  navbar:
    right:
      - icon: github
        text: GitHub
        href: https://github.com/pythonhealthdatascience/quarto-template/
  sidebar:
    logo: images/exeter.png

2.2 index.qmd

A .qmd file is a Quarto Markdown document.

If you’re familiar with R Markdown (.Rmd), these are similar, but .qmd is more flexible.

index.qmd servers as the homepage of your website.

Each .qmd file begins with YAML front matter, enclosed by three dashes (---). This defines metadata such as the page title.

Alternative way of doing this would be # My homepage. TODO: SO WHY DO IT IN YAML?

Below that is the page. Here we just have one sentence: This is my homepage..

---
title: My homepage
---


This is my homepage.

3 Rendering your website

Rendering means converting your Quarto source files into the final website - a colelction of .html pages that live inside a folder called _site.

To render in RStudio…

  1. Open index.qmd in the editor.

[SCREENSHOT]

  1. Click the blue Render button (the arrow icon) at the top of the editor.

[SCREENSHOT]

RStudio will:

  • Create the _sites/ folder containing your rendered site.
  • Open a live preview in your browser.

TODO: EXPLAIN LIVE PREVIEW url… its local host… display via browser…

TipTroubleshooting

The preview may not open automatically if your browser blocks the pop-up. To resolve this, you should either:

  • Click to allow pop-ups in your browsers, then click Render again.
  • Go to the Background Jobs tab in the bottom left. This is where lgos from rendering quarot site are shown. Here, you will find the preview URL. Copy and paste this into browser.

[SCREENSHOT]

3.1 Rendering from the terminal

You can also build your site using command-line tools. The terminal is simply a text-based way to type commands directly, rather than clicking buttons.

Two helpful commands are:

  • quarto render - builds your website.
  • quarto preview - builds and opens a live-updating preview.