This is the repo for the documentation hosted at:

• Current release: quarto.org
• Pre-release: prerelease.quarto.org

Please report issues on quarto.org by opening a "Documentation Issue" in the quarto-dev/quarto-cli repository: New Issue

This section discusses how to contribute to the documentation by rendering a document locally.

This Quarto project uses freeze: true, meaning it will never run computation engines during a project render. No Knitr or Jupyter configuration is needed to build the whole website. The _freeze folder is tracked on the git repo for this purpose. (See about freeze for a reminder of how this works).

What is the impact if you modify (or add) a document:

• If you modify a document that doesn't use any computation (i.e default engine: markdown is used), committing only the changes in the document is enough.
• If you modify a document that uses engine: knitr or engine: jupyter, you need to render the document locally and commit the changes in the _freeze folder as well. See incremental render.

When you render quarto-web, you should use the current Pre-release of Quarto.

To render the whole website locally, you can use the following command:

# Update freeze state if needed
quarto render /docs/path/to/modified-or-added-document.qmd
# Render the whole website using freeze state for all the other docs
quarto render

To manage computational dependencies this project uses

• renv for the R environment (https://rstudio.github.io/renv/) - it will be installed automatically first time the project is run with R.
• uv for the Python environment (https://docs.astral.sh/uv/) - Please install uv if you don't have it yet.

This project uses R 4.3.2 and renv to manage its R dependencies. To install the R environment, you can use the following command at the project root:

Rscript -e "renv::restore()"

The project library will be located under the renv folder.

You don't need to worry about the R environment when you are working on this project. renv sets up .Rprofile to activate the project library when R is ran from the project's root. Just run your R code as usual, and renv will be activated automatically, meaning R will correctly use the project's library.

If you are adding a new document that may use a new package, follow these steps:

• Dependencies are explicitly declared in DESCRIPTION file. So add the new package to the list.
• Run renv::install('package_name') to add the new package to project library, and render your document to test everything is working fine.
• Run renv::snapshot() to update the renv.lock file with the new package and its dependencies.
• Commit the modified DESCRIPTION and renv.lock files with your document change (don't forget any change in the _freeze folder if needed).

Note: Python dependencies are not tracked through renv but are tracked with uv. See below

This project uses uv (https://docs.astral.sh/uv/) to handle Python dependencies. uv takes care of managing dependencies and the virtual environment for you.

To install the Python environment, run the following command at the project root:

uv sync

If you don't have a matching Python version installed, uv will download one automatically.

The virtual environment will be located in the project directory under .venv.

To run a command using the project's Python environment, use uv run:

uv run quarto render docs/path/to/document.qmd

You can also activate the virtual environment directly:

# macOS / Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

Inside VS Code, the Python extension should find the .venv Python version automatically (e.g. Python > Select Interpreter), which Quarto Preview uses. The integrated terminal will also use this Python version without manual activation.

If you are adding a new document that may use a new package, follow these steps:

• Run uv add <package_name> to add the new package to the project. It will update the pyproject.toml and uv.lock files with the new package and its dependencies.
• Commit the modified pyproject.toml and uv.lock files with your document changes (don't forget any changes in the _freeze folder if needed).

Documents running Python with the Knitr engine will go through reticulate. reticulate will use the Python version from .venv --- no specific configuration is needed as reticulate's python discovery mechanism will find it.

The tablular data on options listed in the Reference section are generated automatically by running:

quarto run _tools/reference.ts

This builds the .json files in docs/references based on the Quarto CLI schema. The script assumes you have quarto-cli/ at the same level in your directory structure as quarto-web/.

This project uses Quarto profiles to build two sites from the same source: quarto.org and prerelease.quarto.org.

Phase profiles (rc / prerelease) control release-phase branding. They are declared as a profile group in _quarto.yml:

profile:
  group:
    - [rc, prerelease]   # first entry is the default

The group order determines which phase is active on quarto.org (the main site). Flipping the order (e.g. [rc, prerelease] to [prerelease, rc]) switches the main site between "Release Candidate" and "Pre-release" branding.

Site profile (prerelease-docs) configures everything specific to prerelease.quarto.org: site URL, announcement banner, search index, theme, and the prerelease-subdomain variable.

CI profile (pr-preview) is used by the deploy preview workflow to render draft: true pages as visible. quarto render hides drafts by default, but PR reviewers need to see them.

prerelease-subdomain — site identity variable ("am I the prerelease site?"). Default '' in _quarto.yml, set to prerelease. in _quarto-prerelease-docs.yml. Use for self-referential links (e.g. RevealJS demo links back to its own site).

prerelease-docs-url — version-aware shortcode for content linking. Use in blog posts that reference docs only available on prerelease:

[PDF Accessibility](https://{{< prerelease-docs-url 1.9 >}}quarto.org/docs/output-formats/pdf-accessibility.html)

The shortcode compares its version argument to the version key in _quarto.yml (which tracks the current stable release on main). If they match, docs are on quarto.org (""); if not, they're still on prerelease.quarto.org ("prerelease."). On the prerelease site (prerelease-docs profile), it always returns "prerelease.".

1. Development phase: group is [prerelease, rc] — main site shows "Pre-release"
2. RC phase: flip group to [rc, prerelease] — main site shows "Release Candidate"
3. Release: flip back to [prerelease, rc] for the next development cycle

These flips only affect quarto.org. The prerelease site CI activates prerelease-docs, and the group order determines the phase branding on the prerelease site too.

# Main site with RC branding
quarto preview --profile rc

# Main site with pre-release branding (default when prerelease is first in group)
quarto preview

# Prerelease site
quarto preview --profile prerelease,prerelease-docs

Our GitHub Action workflows are documented in .github/workflows/README.md

You can find some style guidance in _style-guide.md.