Fix profile configuration for prerelease website by cderv · Pull Request #1932 · quarto-dev/quarto-web

cderv · 2026-03-04T13:02:27Z

The prerelease site (prerelease.quarto.org) gets wrong values from the profile system in two ways:

CI sets QUARTO_PROFILE=prerelease-docs, but the profile group [rc, prerelease] auto-adds rc (the group default), giving the prerelease site RC branding instead of pre-release branding.
prerelease-subdomain is defined in the phase profiles (_quarto-prerelease.yml / _quarto-rc.yml), but which subdomain to use is a site concern, not a phase concern. During dev phase, the main site incorrectly links to prerelease.quarto.org.

Additionally, "flip to RC" commits that reorder the profile group get auto-backported to the prerelease branch via port-to-prerelease.yml, causing empty cherry-picks.

Fix

Separate prerelease-subdomain from phase variables:

Base _quarto.yml defines prerelease-subdomain: '' (links to quarto.org)
Only _quarto-prerelease-docs.yml overrides it to prerelease.
Phase profiles (_quarto-prerelease.yml, _quarto-rc.yml) no longer set it

Fix CI to explicitly activate the prerelease profile:

QUARTO_PROFILE changes from prerelease-docs to prerelease,prerelease-docs
This satisfies the profile group so rc is not auto-added
Makes the prerelease site immune to group order changes

Scenario	Active profiles	Title	Links to
quarto.org (RC phase)	base + rc	"Release Candidate"	quarto.org
quarto.org (dev phase)	base + prerelease	"Pre-release"	quarto.org
prerelease.quarto.org	base + prerelease + prerelease-docs	"Pre-release"	prerelease.quarto.org

github-actions · 2026-03-04T13:10:33Z

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-1932.quarto.org

cwickham

This looks great!

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.

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.

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.

cderv · 2026-03-04T18:59:24Z

I'll try to add in there what needs to be done for #1934 before merging

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)

cderv · 2026-03-04T19:50:57Z

@cwickham I added prerelease-link-subdomain variable

This adds a phase-aware variable for linking to prerelease docs from content on main, addressing the use case in #1934.

Unlike prerelease-subdomain (site identity — "am I the prerelease site?"), prerelease-link-subdomain answers "where do prerelease docs live right now?":

Scenario	Active profiles	`prerelease-link-subdomain`	Links resolve to
main (RC phase)	base + rc	`prerelease.`	prerelease.quarto.org
main (dev phase)	base + prerelease	`''`	quarto.org
prerelease site	base + prerelease + prerelease-docs	`prerelease.`	prerelease.quarto.org

Usage in blog posts:

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

During RC, this links to prerelease.quarto.org. After the release (when prerelease merges to main and the group flips back), it automatically switches to quarto.org — no manual edits needed.

github-actions · 2026-03-04T19:58:37Z

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-1932.quarto.org

github-actions · 2026-03-04T20:06:06Z

Successfully created backport PR for prerelease:

[Sync to prerelease] Fix profile configuration for prerelease website #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)

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

cderv · 2026-03-04T21:04:24Z

In fact, we may want release candidate to apply on prerelease website too... 🤔
We just don't want to remove the prerelease-subdomain for prerelease website when we flip to rc.

I'll think about this more to adapt. Not that impacted. At least links are no more broken

cwickham · 2026-03-04T21:08:04Z

I'm also now realising this means next time we go to rc these links go back to prerelease. I wonder if we need more complicated logic that ties to version numbers...

cderv · 2026-03-04T21:11:13Z

I'm also now realising this means next time we go to rc these links go back to prerelease

This I tried to prevent I think 🤔
because I moved the variable in _quarto-prerelease-docs.yml so it will always apply to prerelease website that we build with this profile, but never on the main website.

cwickham · 2026-03-04T21:12:34Z

I'm thinking of the links that use prerelease-link-subdomain, e.g. the blog post.

cderv · 2026-03-04T21:17:22Z

Oh I see, so for the blog post version INSIDE prerelease website?

Because on quarto.org, after rc phase, it will use value inside _quarto.yml, so good.

But on prerelease.quarto.org, after rc phase it will be using _quarto-prerelease-docs.yml value, and stay prelease.

I tried to cover different scenarios in tables above, but maybe I missed something. 🤔

cderv · 2026-03-04T21:26:56Z

Oh now I understand !!

At next RC phase for quarto 1.10, then all the old blog post gets back a prerelease link !!

Is that what you meant ?

So maybe not a good idea at all, and we should keep it internal to docs or to some blog folder.
Like scoped metadata, as gordon did in document.

But in that case, we would need a process or a script to remember

We could also cleanup all {{< meta prerelease-link-subdomain >}} with post render script or any processing WHEN doing the release (when removing rc phase, and merging prerelease in main) 🤷‍♂️

Thanks for seeing this !

Follow-up to #1932. Now that prerelease-subdomain is defined in _quarto-prerelease-docs.yml rather than the phase profiles, the profile group order correctly controls which phase is active on the prerelease site. The explicit prerelease profile activation is no longer needed and prevents RC branding from showing on prerelease.quarto.org during RC phase.

The `prerelease-link-subdomain` variable is phase-aware but not version-aware — on the next RC cycle, old blog posts would incorrectly point to prerelease.quarto.org even though those docs already moved to quarto.org. Add a `prerelease-docs-url` shortcode extension that compares a version argument against the `version` key in `_quarto.yml` to decide whether docs live on quarto.org or prerelease.quarto.org. On the prerelease site (prerelease-docs profile), it always returns "prerelease." regardless of version. Follow-up to quarto-dev#1932, relates to quarto-dev#1934.

…1938) Follow-up to #1932. Now that prerelease-subdomain is defined in _quarto-prerelease-docs.yml rather than the phase profiles, the profile group order correctly controls which phase is active on the prerelease site. The explicit prerelease profile activation is no longer needed and prevents RC branding from showing on prerelease.quarto.org during RC phase.

…1938) Follow-up to #1932. Now that prerelease-subdomain is defined in _quarto-prerelease-docs.yml rather than the phase profiles, the profile group order correctly controls which phase is active on the prerelease site. The explicit prerelease profile activation is no longer needed and prevents RC branding from showing on prerelease.quarto.org during RC phase. (cherry picked from commit a34fdb6)

The `prerelease-link-subdomain` variable is phase-aware but not version-aware — on the next RC cycle, old blog posts would incorrectly point to prerelease.quarto.org even though those docs already moved to quarto.org. Add a `prerelease-docs-url` shortcode extension that compares a version argument against the `version` key in `_quarto.yml` to decide whether docs live on quarto.org or prerelease.quarto.org. On the prerelease site (prerelease-docs profile), it always returns "prerelease." regardless of version. Follow-up to #1932, relates to #1934.

* Replace prerelease-link-subdomain with version-aware shortcode The `prerelease-link-subdomain` variable is phase-aware but not version-aware — on the next RC cycle, old blog posts would incorrectly point to prerelease.quarto.org even though those docs already moved to quarto.org. Add a `prerelease-docs-url` shortcode extension that compares a version argument against the `version` key in `_quarto.yml` to decide whether docs live on quarto.org or prerelease.quarto.org. On the prerelease site (prerelease-docs profile), it always returns "prerelease." regardless of version. Follow-up to #1932, relates to #1934. * Update PDF accessibility blog post to use prerelease-docs-url shortcode

* Replace prerelease-link-subdomain with version-aware shortcode The `prerelease-link-subdomain` variable is phase-aware but not version-aware — on the next RC cycle, old blog posts would incorrectly point to prerelease.quarto.org even though those docs already moved to quarto.org. Add a `prerelease-docs-url` shortcode extension that compares a version argument against the `version` key in `_quarto.yml` to decide whether docs live on quarto.org or prerelease.quarto.org. On the prerelease site (prerelease-docs profile), it always returns "prerelease." regardless of version. Follow-up to #1932, relates to #1934. * Update PDF accessibility blog post to use prerelease-docs-url shortcode (cherry picked from commit 63a21f0)

github-actions bot temporarily deployed to pull request March 4, 2026 13:10 Inactive

cderv requested a review from cwickham March 4, 2026 13:56

cderv mentioned this pull request Mar 4, 2026

pdf accessibility blog post #1934

Merged

cwickham approved these changes Mar 4, 2026

View reviewed changes

cderv added 3 commits March 4, 2026 19:57

Document profile system in README

e5bccfa

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.

cderv force-pushed the fix/profile-subdomain-separation branch from 663a185 to 09f596b Compare March 4, 2026 19:49

github-actions bot temporarily deployed to pull request March 4, 2026 19:58 Inactive

cderv merged commit 8516589 into main Mar 4, 2026
4 checks passed

cderv deleted the fix/profile-subdomain-separation branch March 4, 2026 20:05

github-actions bot mentioned this pull request Mar 4, 2026

[Sync to prerelease] Fix profile configuration for prerelease website #1937

Merged

cderv mentioned this pull request Mar 5, 2026

Fix CI profile to let profile group control phase on prerelease site #1938

Merged

cderv mentioned this pull request Mar 5, 2026

Replace prerelease-link-subdomain with version-aware shortcode #1939

Merged

github-actions bot mentioned this pull request Mar 5, 2026

[Sync to prerelease] Fix CI profile to let profile group control phase on prerelease site #1940

Merged

github-actions bot mentioned this pull request Mar 6, 2026

[Sync to prerelease] Replace prerelease-link-subdomain with version-aware shortcode #1943

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix profile configuration for prerelease website#1932

Fix profile configuration for prerelease website#1932
cderv merged 4 commits intomainfrom
fix/profile-subdomain-separation

cderv commented Mar 4, 2026

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

cwickham left a comment

Uh oh!

cderv commented Mar 4, 2026 •

edited

Loading

Uh oh!

cderv commented Mar 4, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

cderv commented Mar 4, 2026

Uh oh!

cwickham commented Mar 4, 2026

Uh oh!

cderv commented Mar 4, 2026

Uh oh!

cwickham commented Mar 4, 2026

Uh oh!

cderv commented Mar 4, 2026

Uh oh!

cderv commented Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

cderv commented Mar 4, 2026

Fix

Uh oh!

github-actions bot commented Mar 4, 2026

📝 Preview Deployment

Uh oh!

cwickham left a comment

Choose a reason for hiding this comment

Uh oh!

cderv commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cderv commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 4, 2026

📝 Preview Deployment

Uh oh!

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

cderv commented Mar 4, 2026

Uh oh!

cwickham commented Mar 4, 2026

Uh oh!

cderv commented Mar 4, 2026

Uh oh!

cwickham commented Mar 4, 2026

Uh oh!

cderv commented Mar 4, 2026

Uh oh!

cderv commented Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cderv commented Mar 4, 2026 •

edited

Loading

cderv commented Mar 4, 2026 •

edited

Loading