# quarto-web
[](https://github.com/quarto-dev/quarto-cli/releases/latest)
[](https://github.com/quarto-dev/quarto-cli/releases/)
[](https://deepwiki.com/quarto-dev/quarto-web)
This is the repo for the documentation hosted at:
* **Current release:** [quarto.org](https://quarto.org/)
* **Pre-release:** [prerelease.quarto.org](https://prerelease.quarto.org/)
## Reporting Issues
Please report issues on quarto.org by opening a "Documentation Issue" in the `quarto-dev/quarto-cli` repository: [New Issue](https://github.com/quarto-dev/quarto-cli/issues/new/choose)
## Rendering `quarto-web` locally
This section discusses how to contribute to the documentation by rendering a document locally.
### Quarto-web uses a frozen state of computation
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](https://quarto.org/docs/projects/code-execution.html#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](https://quarto.org/docs/projects/code-execution.html#incremental-render).
### Rendering the whole website
When you render `quarto-web`, you should use the current [Pre-release of Quarto](https://quarto.org/docs/download/prerelease.html).
To render the whole website locally, you can use the following command:
```bash
# 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
```
### Installing and managing computation environment
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.
#### R environment for Knitr engine
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:
```bash
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
#### Python environment for Jupyter engine and Knitr through reticulate
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:
```bash
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`:
```bash
uv run quarto render docs/path/to/document.qmd
```
You can also activate the virtual environment directly:
```bash
# 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](https://rstudio.github.io/reticulate/articles/versions.html#order-of-discovery) will find it.
## Reference pages are automatically generated
The tablular data on options listed in the [Reference section](https://quarto.org/docs/reference/) are generated automatically by running:
```
quarto run _tools/reference.ts
```
This builds the `.json` files in `docs/references` based on the [Quarto CLI schema](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/schema). The script assumes you have `quarto-cli/` at the same level in your directory structure as `quarto-web/`.
## Profile System
This project uses [Quarto profiles](https://quarto.org/docs/projects/profiles.html) to build two sites from the same source: [quarto.org](https://quarto.org/) and [prerelease.quarto.org](https://prerelease.quarto.org/).
### Two-layer architecture
**Phase profiles** (`rc` / `prerelease`) control release-phase branding. They are declared as a [profile group](https://quarto.org/docs/projects/profiles.html#profile-groups) in `_quarto.yml`:
```yaml
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.
| File | Purpose |
|---|---|
| `_quarto-prerelease.yml` | Phase variables for the pre-release/development phase |
| `_quarto-rc.yml` | Phase variables for the release candidate phase |
**Site profile** (`prerelease-docs`) configures everything specific to prerelease.quarto.org: site URL, announcement banner, search index, theme, and the `prerelease-subdomain` variable.
| File | Purpose |
|---|---|
| `_quarto-prerelease-docs.yml` | Site-specific configuration for prerelease.quarto.org |
**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.
| File | Purpose |
|---|---|
| `_quarto-pr-preview.yml` | Sets `draft-mode: visible` for deploy previews |
### Subdomain variable and shortcode
**`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:
```markdown
[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."`.
### Release lifecycle
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.
### Local preview
```bash
# 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
```
## GitHub Action Workflows
Our GitHub Action workflows are documented in [`.github/workflows/README.md`](.github/workflows/README.md)
## Accessibility baseline
`_axe-baseline.json` lists the accessibility findings that `quarto call axe` reports as known, not new. Each entry is a finding that quarto-web cannot fix in its own content, a false positive, or an intentional example.
Each entry has a `note` in this format:
```
<type>: <issue-ref>. <Description>.
```
- `<type>` is `upstream`, `third-party`, `false-positive`, or `intentional`. For `third-party`, add the library name: `third-party: leaflet, <issue-ref>.`
- `<issue-ref>` is a full `org/repo#number` reference, for example `quarto-dev/quarto-cli#14378`. If no issue exists, write `no upstream issue`.
- The description gives the cause and the condition to remove the entry. If the entry is limited to some pages, it also gives the reason.
Do not use Markdown links in a note. Do not add commentary, for example the age of an issue.
## Style Guide
You can find some style guidance in [_style-guide.md](_style-guide.md).