From bdff12d2efba1896b5ff41650d69dc8ac93dc4ce Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 4 Mar 2026 13:53:37 +0100 Subject: [PATCH 1/4] Move prerelease-subdomain from phase profiles to base/site profiles prerelease-subdomain is a site concern (which domain am I on?), not a phase concern (prerelease vs RC). Previously, the rc profile set it to empty and the prerelease profile set it to 'prerelease.', which caused the main site to link to prerelease.quarto.org during dev phase. Now the base _quarto.yml defines prerelease-subdomain as empty (links to quarto.org) and only _quarto-prerelease-docs.yml overrides it to 'prerelease.' for the prerelease site. --- _quarto-prerelease-docs.yml | 2 ++ _quarto-prerelease.yml | 3 +-- _quarto-rc.yml | 3 +-- _quarto.yml | 2 ++ 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/_quarto-prerelease-docs.yml b/_quarto-prerelease-docs.yml index bab7751837..967b8d2119 100644 --- a/_quarto-prerelease-docs.yml +++ b/_quarto-prerelease-docs.yml @@ -1,6 +1,8 @@ # Pre-release version number version: v1.9 +prerelease-subdomain: prerelease. + website: title: "Quarto (Pre-release)" image: "quarto-dark-bg-pre.jpeg" diff --git a/_quarto-prerelease.yml b/_quarto-prerelease.yml index c35504b531..9484b55b4c 100644 --- a/_quarto-prerelease.yml +++ b/_quarto-prerelease.yml @@ -1,4 +1,3 @@ prerelease-title: Pre-release prerelease-lower: pre-release -prerelease-mode: "" -prerelease-subdomain: prerelease. \ No newline at end of file +prerelease-mode: "" \ No newline at end of file diff --git a/_quarto-rc.yml b/_quarto-rc.yml index 0f2c2e4d62..3084566f05 100644 --- a/_quarto-rc.yml +++ b/_quarto-rc.yml @@ -1,4 +1,3 @@ prerelease-title: Release Candidate prerelease-lower: release candidate -prerelease-mode: Release Candidate -prerelease-subdomain: '' \ No newline at end of file +prerelease-mode: Release Candidate \ No newline at end of file diff --git a/_quarto.yml b/_quarto.yml index 61b096be5f..be2cd3b101 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -706,6 +706,8 @@ filters: - at: post-quarto path: filters/include-dark.lua +prerelease-subdomain: '' + freeze: true profile: From b8b0a7a728597a80f3f7ae5d427182a098095ab6 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 4 Mar 2026 13:54:20 +0100 Subject: [PATCH 2/4] Fix CI to explicitly activate prerelease profile for prerelease site When CI set QUARTO_PROFILE=prerelease-docs, the profile group [rc, prerelease] auto-added rc (the group default), giving the prerelease site RC branding. Adding 'prerelease' explicitly (prerelease,prerelease-docs) satisfies the group so the default is not auto-added. This also makes the prerelease site immune to "flip to RC" commits that reorder the profile group, eliminating empty cherry-picks when those commits are auto-backported to the prerelease branch. --- .github/workflows/preview.yml | 2 +- .github/workflows/publish.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index c450e4f77e..d32b6a202c 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -103,7 +103,7 @@ jobs: - name: Render uses: quarto-dev/quarto-actions/render@v2 env: - QUARTO_PROFILE: ${{ steps.prerelease-docs-check.outputs.is_prerelease_docs == 'true' && 'prerelease-docs' || '' }} + QUARTO_PROFILE: ${{ steps.prerelease-docs-check.outputs.is_prerelease_docs == 'true' && 'prerelease,prerelease-docs' || '' }} - name: Deploy Preview to Netlify as preview id: netlify-deploy diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 787d467dea..e35cbc3b44 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -47,7 +47,7 @@ jobs: - name: Render uses: quarto-dev/quarto-actions/render@v2 env: - QUARTO_PROFILE: ${{ (inputs.prerelease || (contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name) && github.ref == 'refs/heads/prerelease')) && 'prerelease-docs' || '' }} + QUARTO_PROFILE: ${{ (inputs.prerelease || (contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name) && github.ref == 'refs/heads/prerelease')) && 'prerelease,prerelease-docs' || '' }} - name: Publish release website # Only do this step if From e5bccfa46047dc59ac33abb8bdbb223bc06cb4ce Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 4 Mar 2026 13:54:44 +0100 Subject: [PATCH 3/4] Document profile system in README Explain the two-layer profile architecture (phase profiles vs site profile), what each _quarto-*.yml file does, the release lifecycle, and how to preview locally with different profiles. --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/README.md b/README.md index 4b133d1430..0fc70c114c 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,56 @@ 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 | + +The `prerelease-subdomain` variable is defined as empty (`''`) in `_quarto.yml` (so links point to `quarto.org` by default) and overridden to `prerelease.` only in `_quarto-prerelease-docs.yml`. + +### 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 explicitly activates `prerelease,prerelease-docs`, so it always shows "Pre-release" regardless of group order. + +### 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) From 09f596bd6607594ad9432fd22e2174b71697e79c Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 4 Mar 2026 20:47:25 +0100 Subject: [PATCH 4/4] Add prerelease-link-subdomain for phase-aware linking to prerelease docs Blog posts on main need to link to prerelease.quarto.org during RC phase (when docs only exist there) and switch to quarto.org after release. Unlike prerelease-subdomain (site identity), this variable is phase-aware: - Default: '' (links to quarto.org) - RC profile: 'prerelease.' (docs still on prerelease site) - prerelease-docs profile: 'prerelease.' (prerelease site links to itself) --- README.md | 11 ++++++++++- _quarto-prerelease-docs.yml | 1 + _quarto-rc.yml | 3 ++- _quarto.yml | 1 + 4 files changed, 14 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0fc70c114c..1f39df0869 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,16 @@ The group order determines which phase is active on **quarto.org** (the main sit |---|---| | `_quarto-prerelease-docs.yml` | Site-specific configuration for prerelease.quarto.org | -The `prerelease-subdomain` variable is defined as empty (`''`) in `_quarto.yml` (so links point to `quarto.org` by default) and overridden to `prerelease.` only in `_quarto-prerelease-docs.yml`. +### Subdomain variables + +Two variables control how links resolve across builds. Both use the same pattern — `https://{{< meta VAR >}}quarto.org/...` — but serve different purposes: + +| Variable | Purpose | Default | Set by `rc` | Set by `prerelease-docs` | +|---|---|---|---|---| +| `prerelease-subdomain` | **Site identity** — "am I the prerelease site?" | `''` | — | `prerelease.` | +| `prerelease-link-subdomain` | **Content linking** — "where do prerelease docs live right now?" | `''` | `prerelease.` | `prerelease.` | + +Use `prerelease-subdomain` for self-referential links (e.g. RevealJS demo links back to its own site). Use `prerelease-link-subdomain` for content on `main` that references docs only available on prerelease during RC phase (e.g. blog posts announcing upcoming features). ### Release lifecycle diff --git a/_quarto-prerelease-docs.yml b/_quarto-prerelease-docs.yml index 967b8d2119..6944203867 100644 --- a/_quarto-prerelease-docs.yml +++ b/_quarto-prerelease-docs.yml @@ -2,6 +2,7 @@ version: v1.9 prerelease-subdomain: prerelease. +prerelease-link-subdomain: prerelease. website: title: "Quarto (Pre-release)" diff --git a/_quarto-rc.yml b/_quarto-rc.yml index 3084566f05..7d68f7fe2d 100644 --- a/_quarto-rc.yml +++ b/_quarto-rc.yml @@ -1,3 +1,4 @@ prerelease-title: Release Candidate prerelease-lower: release candidate -prerelease-mode: Release Candidate \ No newline at end of file +prerelease-mode: Release Candidate +prerelease-link-subdomain: prerelease. \ No newline at end of file diff --git a/_quarto.yml b/_quarto.yml index be2cd3b101..1bbd0d773b 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -707,6 +707,7 @@ filters: path: filters/include-dark.lua prerelease-subdomain: '' +prerelease-link-subdomain: '' freeze: true