Projects

Quarto projects

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).

One of the most important features of Quarto Projects is the ability to share YAML metadata options across multiple documents.

Quarto projects

Some formats must be created within a Quarto project:

• Websites
• Blogs
• Books

Anatomy of a Quarto project

A Quarto Project is a directory that contains a file called _quarto.yml.

This is a Quarto Project.

my-folder/
├── _quarto.yml
├── my-document.ipynb

This is not.

my-folder/
├── my-document.ipynb

Quarto projects include a _quarto.yml configuration file so that every document in the project inherits the metadata in that file. So, if you think about a blog, you probably want all your posts to have the same theme. If you use the Quarto command for making a new blog, it will automatically be a project, and you can configure the theme for all pages in the _quarto.yml file.

_quarto.yml

A YAML file with particular keys and values that Quarto recognizes. Unrecognized keys are ignored.

_quarto.yml

project:
  title: "Creating Polished, Branded Documents with Quarto"

_quarto.yml

A YAML file with particular keys and values that Quarto recognizes. Unrecognized keys are ignored.

_quarto.yml

project:
  type: website
  output-dir: docs

website:
  page-navigation: true
  title: "Creating Polished, Branded Documents with Quarto"
  description: "R/Pharma 2025 Workshop"

  repo-url: 2025-11-04_branded-quarto
  repo-actions: [edit, issue]

  open-graph: true

  sidebar:
    background: "#EDF3F9"
    logo: https://rinpharma.com/images/logo-rinpharma.png
    pinned: true
    align: center
    style: docked
    search: true
    collapse-level: 2
    contents:
      - href: index.qmd
        text: Home
      - href: 00-introduction/index.qmd
        text: Introduction
      - href: 01-documents/index.qmd
        text: Documents
      - href: 02-projects/index.qmd
        text: Projects
      - href: 03-theming/index.qmd
        text: Theming
      - href: 04-publishing/index.qmd
        text: Publishing
        
  page-footer:
    right: "This page is built with ❤️ and [Quarto](https://quarto.org/)."
    left: "© Copyright 2025, Isabella Velásquez"
    background: "#D1D9E3"

format:
  html:
    theme:
      light: [brand, styles.scss]
    toc: true
    code-copy: true
    code-overflow: wrap
    mainfont: "Source Sans 3"

execute:
  freeze: auto
  echo: true

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:

_quarto.yml

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

_quarto.yml

execute:
  freeze: auto  # re-render only when source changes

Rendering a bunch of files can be quite time consuming depending on the computations required. The freeze option specifies if computational documents should never be re-rendered during a global project render, or only be re-rendered when their source file changes. Freeze can used when you have either a large number of collaborators or many computational documents created over a long period of time. In these cases, it can be challenging to fully re-execute every document when you render the site. This could be because some documents have environment-specific requirements or one of your teammates wrote something in Python, which you don’t have installed. Using freeze ensures that you can always reproducibly render your site.

Our turn

• In your folder, convert the document into a project by running:

Terminal

quarto create project

• For Type, select website.
• For Directory, type ..
• For Title, give it a title related to pharma.

Quarto will create several files, including _quarto.yml (you may need to refresh the files pane).

• Open _quarto.yml.

Our turn

• Add final-report.qmd under Home and give it the text Report:

_quarto.yml

navbar:
  left:
    - href: index.qmd
      text: Home
    - href: final-report.qmd
      text: Report

• Open about.qmd and add some information about yourself. Feel free to edit the YAML.
• Render the project, then explore your new website!

Terminal

quarto preview