Replace prerelease-link-subdomain with version-aware shortcode#1939
Replace prerelease-link-subdomain with version-aware shortcode#1939
Conversation
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-1939.quarto.org |
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-1939.quarto.org |
| - at: post-quarto | ||
| path: filters/include-dark.lua | ||
|
|
||
| version: '1.8' |
There was a problem hiding this comment.
This is the new required addition. We would version inside _quarto.yml, with different value on main and on prerelease branches.
This way we can behave differently based on this info retrieved in Lua.
This would replace version: '1.9' in _quarto-prerelease-docs.yml - or duplicate.
I mean, if we do modify in prerelease branch version: 1.9 in _quarto.yml, it won't be possible to forgot updating when we merge prerelease in main.
Keeping it in _quarto-prerelease-docs.yml too just allows to be able to do
quarto render --profile prerelease-docs
even from main branch to activate the prerelease profile feature, if they need to be verify.
But usually --profile prerelease-docs is only ever used with prerelease branch
Hope this is clear.
There was a problem hiding this comment.
I think I understand. Is it worth adding an item to our release checklist to verify/update this value?
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.
pandoc.types.Version provides element-wise comparison so older version args (e.g. 1.8 when main is at 1.9) correctly resolve to quarto.org instead of prerelease.quarto.org.
5b82d94 to
9a4c7aa
Compare
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-1939.quarto.org 🔄 Modified Documents |
|
I have also modified the blog post just merged to use this new shortcode. |
Use quarto.shortcode.error_output() for clear error messages when version metadata is missing or version arguments are malformed. Fix missing trailing newline in _quarto-rc.yml.
* 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)
|
Successfully created backport PR for |
* 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)
prerelease-link-subdomainis phase-aware but not version-aware. On the next RC cycle (e.g. v1.10), old blog posts about v1.9 features would incorrectly flip back toprerelease.quarto.orgeven though those docs already moved to quarto.org.Fix
Replace the variable with a
prerelease-docs-urlshortcode extension that takes a version argument:The shortcode uses two rules:
prerelease-docsprofile active): always returnprerelease.versionkey in_quarto.ymlusingpandoc.types.Version. Ifarg <= version, docs are on quarto.org (return""). Ifarg > version, docs are still only on prerelease (returnprerelease.).A new
versionkey in_quarto.ymltracks the current stable release ('1.8'on main today). The_quarto-prerelease-docs.ymloverrides it to'1.9'but the shortcode never reaches the comparison on the prerelease site (rule 1 short-circuits). The version drops thevprefix for clean comparison; the announcement banner adds it back inline.Lifecycle of a blog post
A blog post on
mainannounces a v1.9 feature using{{< prerelease-docs-url 1.9 >}}. The blog post itself never changes — the links flip automatically as releases happen:On quarto.org (version comparison):
versionin_quarto.ymlOn prerelease.quarto.org (
prerelease-docsprofile short-circuits):All links always go to prerelease.quarto.org regardless of version, since the prerelease site hosts its own copy of the docs.
Testing
Verified each lifecycle row by rendering a test blog post and checking output links. For rows requiring a specific
versionvalue,_quarto.ymlwas temporarily edited.versionquarto render <post>quarto render <post> --profile rcquarto render <post>quarto render <post> --profile prereleasequarto render <post> --profile "prerelease,prerelease-docs"Both quoted (
"1.9") and unquoted (1.9) argument forms work correctly.Follow-up to #1932, relates to #1934 and #1938.