Replace pre-release feature includes with version-aware shortcode

_extensions/prerelease/README.md

@@ -0,0 +1,52 @@
+# Prerelease Extension
+
+Version-aware shortcodes for prerelease content on quarto-web. Both shortcodes use the `version` key from `_quarto.yml` (or `_quarto-prerelease-docs.yml` on the prerelease profile) to determine whether a feature version has been released.
+
+## Shortcodes
+
+### `prerelease-docs-url`
+
+Returns `"prerelease."` when the referenced version's docs live on prerelease.quarto.org, or `""` when they're on quarto.org. Use in link URLs:
+
+```markdown
+[documentation](https://{{< prerelease-docs-url 1.9 >}}quarto.org/docs/feature.html)
+```
+
+### `prerelease-callout`
+
+Shows a version-aware callout note. Two modes:
+
+**Feature docs** (default) — callout disappears after release:
+
+```markdown
+{{< prerelease-callout 1.9 >}}
+```
+
+- Unreleased: shows "Pre-release Feature" callout with link to prerelease download
+- Released: shows nothing
+
+**Blog posts** (`type="blog"`) — callout text changes after release:
+
+```markdown
+{{< prerelease-callout 1.9 type="blog" >}}
+```
+
+- Unreleased: shows "Pre-release Feature" callout with link to prerelease download
+- Released: shows "Quarto X.Y Feature" callout with link to stable download page
+
+## Version comparison logic
+
+On the **main site** (`version` = current stable release): a feature is unreleased when `ref_version > site_version`.
+
+On the **prerelease site** (profile `prerelease-docs`, `version` = current prerelease cycle): a feature is unreleased when `ref_version >= site_version`.
+
+The `>=` vs `>` difference handles the fact that the prerelease site's version equals the in-progress release, while main's version equals the last stable release.
+
+### Example scenarios (feature docs)
+
+| Phase | Site | `version` | ref | Unreleased? | Output |
+|---|---|---|---|---|---|
+| 1.9 in dev | main | 1.8 | 1.9 | 1.9 > 1.8 ✓ | Pre-release callout |
+| 1.9 in dev | prerelease | 1.9 | 1.9 | 1.9 >= 1.9 ✓ | Pre-release callout |
+| 1.9 released | main | 1.9 | 1.9 | 1.9 > 1.9 ✗ | Nothing |
+| 1.9 released | prerelease | 2.0 | 1.9 | 1.9 >= 2.0 ✗ | Nothing |

_extensions/prerelease-docs-url/_extension.yml → _extensions/prerelease/_extension.yml

@@ -1,6 +1,6 @@
-title: Prerelease Docs URL
+title: Prerelease
 author: Quarto
 version: 0.0.1
 contributes:
   shortcodes:
-    - prerelease-docs-url.lua
+    - prerelease.lua

_extensions/prerelease/prerelease.lua

@@ -0,0 +1,152 @@
+-- Version-aware shortcodes for prerelease content.
+--
+-- prerelease-docs-url:
+--   {{< prerelease-docs-url 1.9 >}}
+--   Returns "prerelease." when the referenced version's docs live on
+--   prerelease.quarto.org, or "" when they're on quarto.org.
+--
+-- prerelease-callout:
+--   {{< prerelease-callout 1.9 >}}
+--   Shows a "Pre-release Feature" callout when the referenced version is
+--   unreleased. Shows nothing once the version is released.
+--
+--   {{< prerelease-callout 1.9 type="blog" >}}
+--   Blog mode: shows "Pre-release Feature" callout when unreleased,
+--   switches to "Quarto X.Y Feature" callout once released.
+--
+-- Both shortcodes use the `version` key from _quarto.yml metadata and
+-- the `prerelease-docs` profile to determine whether a version is released.
+
+--- Strip surrounding quotes from a shortcode argument.
+local function strip_quotes(s)
+  return s:gsub('^"(.*)"$', '%1'):gsub("^'(.*)'$", '%1')
+end
+
+--- Parse the version argument and site version metadata.
+-- Returns ref_version, branch_version (as pandoc.types.Version), or
+-- nil plus an error Blocks/Inlines on failure.
+local function parse_versions(shortcode_name, args, meta, context)
+  local ref_str = quarto.shortcode.read_arg(args, 1)
+  if ref_str == nil then
+    return nil, nil, quarto.shortcode.error_output(
+      shortcode_name,
+      "requires a version argument, e.g. {{< " .. shortcode_name .. " 1.9 >}}",
+      context
+    )
+  end
+  ref_str = strip_quotes(ref_str)
+
+  local version_str = meta["version"] and pandoc.utils.stringify(meta["version"]) or nil
+  if not version_str or version_str == "" then
+    return nil, nil, quarto.shortcode.error_output(
+      shortcode_name,
+      "missing 'version' in document metadata",
+      context
+    )
+  end
+
+  local ok_branch, branch_version = pcall(pandoc.types.Version, version_str)
+  if not ok_branch then
+    return nil, nil, quarto.shortcode.error_output(
+      shortcode_name,
+      "invalid metadata version '" .. version_str .. "'",
+      context
+    )
+  end
+
+  local ok_ref, ref_version = pcall(pandoc.types.Version, ref_str)
+  if not ok_ref then
+    return nil, nil, quarto.shortcode.error_output(
+      shortcode_name,
+      "invalid version argument '" .. ref_str .. "'",
+      context
+    )
+  end
+
+  return ref_version, branch_version, nil
+end
+
+--- Check whether a referenced version is unreleased.
+-- On prerelease site (profile prerelease-docs): ref >= site version
+-- On main site: ref > site version
+local function is_unreleased(ref_version, branch_version)
+  if quarto.project.profile:includes("prerelease-docs") then
+    return ref_version >= branch_version
+  else
+    return ref_version > branch_version
+  end
+end
+
+--- Parse a markdown string into pandoc Blocks.
+local function md_to_blocks(md)
+  return pandoc.read(md, "markdown").blocks
+end
+
+-- Shortcode: prerelease-docs-url
+local function docs_url_handler(args, kwargs, meta, raw_args, context)
+  local ref_version, branch_version, err = parse_versions(
+    "prerelease-docs-url", args, meta, context
+  )
+  if err then return err end
+
+  -- On the prerelease site, always link to prerelease
+  if quarto.project.profile:includes("prerelease-docs") then
+    return pandoc.Str("prerelease.")
+  end
+
+  if ref_version <= branch_version then
+    return pandoc.Str("")
+  else
+    return pandoc.Str("prerelease.")
+  end
+end
+
+-- Shortcode: prerelease-callout
+local function callout_handler(args, kwargs, meta, raw_args, context)
+  local ref_version, branch_version, err = parse_versions(
+    "prerelease-callout", args, meta, context
+  )
+  if err then return err end
+
+  local ref_str = strip_quotes(quarto.shortcode.read_arg(args, 1))
+  local callout_type = kwargs["type"] or ""
+  local is_blog = callout_type == "blog"
+  local unreleased = is_unreleased(ref_version, branch_version)
+
+  if unreleased then
+    -- Pre-release callout (both feature docs and blog)
+    local content = md_to_blocks(
+      "This feature is new in the upcoming Quarto " .. ref_str .. " release. " ..
+      "To use the feature now, you'll need to " ..
+      "[download and install](/docs/download/prerelease.qmd) " ..
+      "the Quarto pre-release."
+    )
+    return quarto.Callout({
+      type = "note",
+      title = "Pre-release Feature",
+      content = content,
+    })
+  end
+
+  if is_blog then
+    -- Released blog callout
+    local content = md_to_blocks(
+      "This post is part of a series highlighting new features in the " ..
+      ref_str .. " release of Quarto. Get the latest release on the " ..
+      "[download page](/docs/download/index.qmd)."
+    )
+    return quarto.Callout({
+      type = "note",
+      title = "Quarto " .. ref_str .. " Feature",
+      content = content,
+    })
+  end
+
+  -- Feature docs, already released: show nothing
+  return pandoc.Blocks({})
+end
+
+return {
+  ["prerelease-docs-url"] = docs_url_handler,
+  ["prerelease-callout"] = callout_handler,
+}

docs/advanced/jupyter/kernel-execution.qmd

@@ -25,7 +25,7 @@ In `python` and `julia` kernels, the setup and cleanup cells are defined by the
 
 ### Adding support to a Jupyter kernel
 
-{{< include /docs/prerelease/1.5/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.5 >}}
 
 If a Jupyter kernel wants to execute in awareness of Quarto's context, it should signal its support by adding the following files to the kernelspec directory:
 
@@ -42,7 +42,7 @@ See the [source for more](https://github.com/quarto-dev/quarto_echo_kernel).
 
 ## Quarto document options
 
-{{< include /docs/prerelease/1.5/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.5 >}}
 
 Jupyter kernels can have access to a number of Quarto options that can affect cell execution.
 
@@ -74,7 +74,7 @@ Quarto offers built-in support for `julia` and `python` kernels by default, see
 
 ### Adding support to a Jupyter kernel
 
-{{< include /docs/prerelease/1.5/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.5 >}}
 
 Arbitrary Jupyter kernels can indicate support for daemons. To do so, provide a `quarto_setup_cell` file in the kernelspec directory so that setup cells can be executed, and ensure that the execution of the setup cell returns an output result with metadata indicating support for running as a daemon. The supported metadata options are:
 

docs/blog/posts/2023-03-13-code-annotation/index.qmd

@@ -14,7 +14,7 @@ image-alt: "Screenshot a code chunk with annotations. Annotations appear in the
 code-annotations: below
 ---
 
-{{< include ../_quarto-1.3-feature.qmd >}}
+{{< prerelease-callout 1.3 type="blog" >}}
 
 Code blocks and executable code cells in Quarto may now include line-based annotations. Line-based annotations provide a way to attach explanation to lines of code much like footnotes.
 

docs/blog/posts/2023-03-15-multi-format/index.qmd

@@ -17,7 +17,7 @@ format:
   docx: default
 ---
 
-{{< include ../_quarto-1.3-feature.qmd >}}
+{{< prerelease-callout 1.3 type="blog" >}}
 
 Starting in Quarto 1.3, HTML pages (either standalone or in a website) can automatically include links to other formats specified in the document front matter. For example, the following document front matter:
 

docs/blog/posts/2023-03-17-jupyter-cell-embedding/index.qmd

@@ -13,7 +13,7 @@ image: embed.png
 image-alt: "A screenshot of a Quarto page that includes a plot, below the plot is the phrase Source: penguins.ipynb."
 ---
 
-{{< include ../_quarto-1.3-feature.qmd >}}
+{{< prerelease-callout 1.3 type="blog" >}}
 
 Starting in Quarto 1.3, you can include the output of an external Jupyter notebook in a Quarto document with the `embed` shortcode. To embed a notebook cell, provide the path to a Jupyter Notebook and a cell identifier. For example, this notebook called `penguins.ipynb` has a cell labelled `fig-bill-scatter`:
 

docs/blog/posts/2023-03-20-confluence/index.qmd

@@ -13,7 +13,7 @@ image: confluence-logo-gradient-blue-attribution_rgb@2x.png
 image-alt: "Atlassian Confluence Logo"
 ---
 
-{{< include ../_quarto-1.3-feature.qmd >}}
+{{< prerelease-callout 1.3 type="blog" >}}
 
 [Atlassian Confluence](https://www.atlassian.com/software/confluence) is a publishing platform for supporting team collaboration. Confluence has a variety of hosting options which include both free and paid subscription plans.
 

docs/blog/posts/2026-03-05-pdf-accessibility-and-standards/index.qmd

@@ -8,7 +8,7 @@ image: thumbnail.png
 image-alt: "Quarto icon, PDF file icon, accessibility icon, and validation shield"
 ---
 
-{{< include ../_quarto-1.9-feature.qmd >}}
+{{< prerelease-callout 1.9 type="blog" >}}
 
 2025 was a big year for PDF accessibility. LaTeX and Typst both released support for PDF tagging and accessibility standards, just in time for new regulations in the [EU](https://en.wikipedia.org/wiki/European_Accessibility_Act) (June 2025) and [US](https://accessible.org/ada-title-ii-web-accessibility/) (April 2026).  
 

docs/computations/julia.qmd

@@ -108,7 +108,7 @@ display(plot(x -> sin(4x), y -> sin(5y), 0, 2))
 
 # Using the `julia` engine
 
-{{< include /docs/prerelease/1.5/_pre-release-feature.qmd >}}
+{{< prerelease-callout 1.5 >}}
 
 ## Installation {#installation-julia-engine}