Fix profile configuration for prerelease website (#1932) (#1937)

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

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

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

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

(cherry picked from commit 8516589)

Co-authored-by: Christophe Dervieux <christophe.dervieux@gmail.com>

Author: github-actions[bot]

.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

.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 

README.md

@@ -105,6 +105,65 @@ 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 |
+
+### 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
+
+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)

_quarto-prerelease-docs.yml

@@ -1,6 +1,9 @@
 # Pre-release version number
 version: v1.9
 
+prerelease-subdomain: prerelease.
+prerelease-link-subdomain: prerelease.
+
 website:
   title: "Quarto (Pre-release)"
   image: "quarto-dark-bg-pre.jpeg"

_quarto-prerelease.yml

@@ -1,4 +1,3 @@
 prerelease-title: Pre-release
 prerelease-lower: pre-release
-prerelease-mode: ""
-prerelease-subdomain: prerelease.
+prerelease-mode: ""

_quarto-rc.yml

@@ -1,4 +1,4 @@
 prerelease-title: Release Candidate
 prerelease-lower: release candidate
 prerelease-mode: Release Candidate
-prerelease-subdomain: ''
+prerelease-link-subdomain: prerelease.

_quarto.yml

@@ -712,6 +712,9 @@ filters:
   - at: post-quarto
     path: filters/include-dark.lua
 
+prerelease-subdomain: ''
+prerelease-link-subdomain: ''
+
 freeze: true
 
 profile: