Websites and books

Reproducible publishing with Quarto

Dr. Mine Çetinkaya-Rundel

Duke University

Posit, PBC

Dr. Charlotte Wickham

Posit, PBC

2024-08-04

Before we move on…Publishing

Terminal

quarto publish hello-penguins.qmd

Open the next module

Option 1: Start the project 3a-websites.

Option 2: Launch the project in 3a-websites.

Anatomy of a Quarto project

Quarto projects

• Quarto projects have a _quarto.yml file

• The type field in this file indicates the type of project:

  • default: Collection of documents

  • website: Websites (and blogs)

  • books: Books 😃

Our turn

Let’s build a website together from all of the documents we’ve created so far and highlight the following features of Quarto websites:

• _quarto.yml

• index.qmd / landing page

• Navigation: left and right under navbar; contents under sidebar.

• Themes and dark theme toggle

• Publishing: quarto publish

Our turn: Code snippets

_quarto.yml

project:
  type: website

website:
  title: "default"
  navbar:
    left:
      - href: index.qmd
        text: Home

index.qmd

---
title: "default"
---

This is a Quarto website.

To learn more about Quarto websites visit <https://quarto.org/docs/websites>.

Your turn

Option 1: Go back to the project 3a-websites-books.

Option 2: Go back to the project in 3a-websites-books.

---

Pick up where we left off and

• Add an about page.
• Look at the _quarto.yml for the workshop site. Find something you like and add it to your site.

15:00

Wrap up

Freeze

• The freeze option controls when/if computational documents be re-rendered during a global project render:

  •    execute:
         freeze: true # never re-render during project render

  •    execute:
         freeze: auto  # re-render when source file changes

  •   execute:
        freeze: false  # always re-render

• The freeze option is typically added to a _metadata.yml file within a specific directory, affecting all files in that directory.

• For blogs, set freeze in _metadata.yml at the root of the posts directory.

• You can have it only within specific subdirectories for more complex sites.

Freeze vs. cache

• Cache stores the results of computations for a specific file.

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

• cache can also be set at the chunk level. Consider using the cache for computationally expensive chunks.

Publishing

See https://quarto.org/docs/publishing for publishing options other than Quarto Pub.

Books

Quarto books

• Books and websites are very similar in that they associate multiple pages/resources into a connected resource

Website

_quarto.yml

project:
  type: website

website: 
  navbar:
    left:
      - index.qmd
      - hello-penguins.qmd

Book

_quarto.yml

project:
  type: book

book: 
  chapters:
    - index.qmd
    - hello-penguins.qmd

Our turn

Let’s build a book together from all of the documents we’ve created so far and highlight the following features of Quarto books:

• _quarto.yml

• index.qmd / landing page / change landing page

• Add a PDF version

• Cross references

• Sections

Your turn

Option 1: Start the project 3b-books.

Option 2: Launch the project in 3b-books.

---

Pick up where we left off and

• Give a title to your book.
• Try dividing the chapters in to Parts
• Cross reference a figure (e.g. the one in tables-figures.qmd) from another chapter.

10:00

Wrap up

Questions

Any questions / anything you’d like to review before we wrap up this module?