Websites Pt. 1

Session 2: AEA Replication in Quarto

Cynthia Huang

Tuesday, July 18, 2023

Websites are Projects

Anatomy of a Quarto Website

🔗 github.com/cynthiahqy/monash-quarto-aea

.
├── 00-pre-workshop.qmd
├── 01a-hello-quarto
│   ├── images
│   ├── index.qmd
│   └── slides.qmd
...01d...04d...
├── index.qmd
├── about.qmd
├── day01-exercises.zip
├── images
│   └── cynthia-profile.jpg
├── _quarto.yml
├── LICENSE
├── README.md
├── README.qmd
├── docs
│   ├── 00-pre-workshop.html
│   ├── 01a-hello-quarto
│   ├── 01b-formats
│   ├── 01c-articles
│   ├── 01d-wrap-up
│   ├── about.html
│   ├── day01-exercises.zip
│   ├── images
│   ├── index.html
│   ├── search.json
│   └── site_libs
├── _freeze
│   ├── 00-pre-workshop
│   ├── 01a-hello-quarto
│   ├── 01b-docs
│   ├── 01b-formats
│   ├── 01c-articles
│   └── site_libs
├── references.bib
└── style
    └── slides.scss

• Config File _quarto.yml with:
  • Project options
  • Website options
  • Shared document options
• Multiple .qmd files
• Additional assets such as code, data, images, pdfs, zip etc.
• Rendered website ready for publishing

Quarto Projects…

are directories that provide:

• A way to render all or some of the files in a directory with a single command (e.g. quarto render myproject).

• A way to share YAML configuration across multiple documents.

• The ability to redirect output artifacts to another directory.

• The ability to freeze rendered output (i.e. don’t re-execute documents unless they have changed).

Projects types

Every project has a _quarto.yml config file:

_quarto.yml

project:
  type: website
  output-dir: docs
...

The type field indicates the type of project:

• default: Collection of documents

• website: Websites (and blogs)!

• books: Books

We will focus on Websites.

Projects options for Websites

• output-dir field controls where rendered output goes. Defaults to _site

_quarto.yml

project:
  type: website
  output-dir: docs
  render:
    - "index.qmd"
    - "about.qmd"
    - "00-pre-workshop.qmd"
    - "01*/*.qmd"
  resources:
    - "day01-exercises.zip"

Projects options for Websites

• render: lists which files to render. Defaults to all files.
• resources: specifies additional files that should be copied to the output directory.

_quarto.yml

project:
  type: website
  output-dir: docs
  render:
    - "index.qmd"
    - "about.qmd"
    - "00-pre-workshop.qmd"
    - "01*/*.qmd"
  resources:
    - "day01-exercises.zip"

See Render Targets and Site Resources in the Quarto Website Guide for more details.

Comments in .yml files

Use # to add comments.

_quarto.yml

project:
  type: website
  output-dir: docs
  ## which pages to include in the website
  render:
    - "index.qmd"
    - "about.qmd"
    - "00-pre-workshop.qmd"
    - "01*/*.qmd"
  ## non-page resources for your website
  resources:
    - "day01-exercises.zip"

Rendering Websites

🔗 github.com/cynthiahqy/monash-quarto-aea

.
├── 00-pre-workshop.qmd
├── 01a-hello-quarto
│   ├── images
│   ├── index.qmd
│   └── slides.qmd
├── index.qmd
├── about.qmd
├── day01-exercises.zip
...01d...04d...
...README...LICENSE...
├── _quarto.yml
├── _freeze/
├── docs/
├── references.bib
└── style
    └── slides.scss

_quarto.yml

project:
  type: website
  output-dir: docs
  render:
    - "index.qmd"
    - "about.qmd"
    - "00-pre-workshop.qmd"
    - "01*/*.qmd"
  resources:
    - "day01-exercises.zip"

Website Options

Available Features

• Navigation: Top navbars, Sidebars
• Tools: Search, Social Media, Comments, Google Analytics
• Content: Listings, About Pages

For a full list of available options see quarto.org > Reference > Projects > Websites. Include these options under the website: field.

Your Turn: Website Options

Open up the workshop website. Pick a YAML option from below and figure out what it does. You might find these links useful: Website Navigation, Website Options. Compare with your neighbour.

10:00

website:
  title: "Meeting AEA Replication standards using Quarto and GitHub"
  description: "Jul 18-20 Workshop on Quarto for Department of Economics, Monash University"
  page-navigation: true
  page-footer:
  right: "This page is built with 💚 and [Quarto](https://quarto.org/)."
  left: "© Copyright 2023, Cynthia Huang"

  sidebar:
    pinned: true
    align: center
    style: docked
    search: true
    collapse-level: 2

    tools:
      - icon: github
        href: https://github.com/cynthiahqy/monash-quarto-aea
        text: "GitHub organization"

    contents:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
      - href: 00-pre-workshop.qmd
        text: Pre-work
      - text: "---"
      - section: "Getting to Know Quarto"
        contents:
          - href: 01a-hello-quarto/index.qmd
            text: Hello Quarto!

Our Turn: Rendering Quarto Replication Website

• Open up the quarto-replication template project again.
• Render and preview the website using quarto::quarto_render() and quarto::quarto_preview()
• Add the file replication-pkg/README.qmd as a page the sidebar. You will need:
  • to change the file format from gfm to html
  • make sure the file is targeted when the projec renders (add to render if not)
  • add a href link to the file in the contents option of sidebar

Your Turn: Customising your Replication Website

• What happens if you add href link to the sidebar without specifying text?
• How can we change the title of the sidebar?
• What features or content would you like to add to the website?

10:00