Release v0.15.0 preparation (google#2627)

Author: chalin

docsy.dev/config/_default/params.yaml

@@ -7,9 +7,9 @@
 #   status: archived # Then fetch include
 
 tdVersion:
-  latest: &tdLatestVers v0.14.3
-  dev: &tdDevVers v0.15.0-dev
-  buildId: &tdBuildId 040-over-main-7a0b370f
+  latest: &tdLatestVers v0.15.0
+  dev: &tdDevVers v0.15.1-dev
+  buildId: &tdBuildId ''
 
 version: *tdDevVers
 version_menu: *tdDevVers

docsy.dev/config/doc-rooted/params.yaml

@@ -1,9 +1,9 @@
 # cSpell:ignore pagelinks
 
 tdVersion:
-  latest: &tdLatestVers v0.14.3
-  dev: &tdDevVers v0.15.0-dev
-  buildId: &tdBuildId 040-over-main-7a0b370f
+  latest: &tdLatestVers v0.15.0
+  dev: &tdDevVers v0.15.1-dev
+  buildId: &tdBuildId ''
 
 version: &tdDocRootedVers Doc-rooted of Next
 version_menu: *tdLatestVers

docsy.dev/config/production/params.yaml

@@ -1,9 +1,9 @@
 # cSpell:ignore pagelinks
 
 tdVersion:
-  latest: &tdLatestVers v0.14.3
-  dev: &tdDevVers v0.15.0-dev
-  buildId: &tdBuildId 040-over-main-7a0b370f
+  latest: &tdLatestVers v0.15.0
+  dev: &tdDevVers v0.15.1-dev
+  buildId: &tdBuildId ''
 
 version: *tdLatestVers
 version_menu: *tdLatestVers

docsy.dev/content/en/blog/2025/0.13.0.md

@@ -3,6 +3,10 @@ title: Release 0.13.0 report and upgrade guide
 linkTitle: Release 0.13.0
 date: 2025-11-24
 lastmod: 2026-02-07
+description: >-
+  Release report and upgrade guide for Docsy 0.13.0, covering active TOC entry
+  tracking, alert shortcode improvements, accessibility enhancements, and
+  section sidebar root.
 author: >-
   [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)),
   for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)

docsy.dev/content/en/blog/2026/0.14.0.md

@@ -3,6 +3,10 @@ title: Release 0.14.0 report and upgrade guide
 linkTitle: Release 0.14.0
 date: 2026-02-10
 lastmod: 2026-02-17
+description: >-
+  Release report and upgrade guide for Docsy 0.14.0, covering markdown alert
+  syntax, navbar style improvements, heading aliases and in-page targets, and
+  improved separation of project and internal SCSS files.
 author: >-
   [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)),
   for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)

docsy.dev/content/en/blog/2026/0.15.0.md

@@ -1,8 +1,12 @@
 ---
 title: Release 0.15.0 report and upgrade guide
 linkTitle: Release 0.15.0
-date: 2026-04-30
-lastmod: 2026-04-30
+date: 2026-05-01
+lastmod: 2026-05-01
+description: >-
+  Release report and upgrade guide for Docsy 0.15.0, covering agent support,
+  doc-rooted sites, version menus, community and footer links, and card
+  shortcode rendering.
 author: >-
   [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)),
   for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)
@@ -32,8 +36,9 @@ cSpell:ignore: afdocs doc-rooted llms markdownify RenderString
   - Generated `llms.txt`
   - Markdown page output
   - "View Markdown" page-meta link
-- **[Doc-rooted sites](#doc-rooted-sites)**: documented pattern and example
-  variant for sites whose `docs` section is published at the site root
+- **[Doc-rooted sites](#doc-rooted-sites)** (experimental): documented pattern
+  and example variant for sites whose `docs` section is published at the site
+  root
 - **[Version menu entries](#version-menu)**: headings, separators, per-entry
   page-link behavior, and kind-specific styling
 - **Content, shortcodes, and internationalization**:
@@ -68,7 +73,7 @@ and use your site content, including:
 - A _View Markdown_ page-meta link when a Markdown page alternative exists.
 
 To learn more, including configuration details on how to enable agent support
-for your site, see [Agent support][].
+for your site, see [Agent support][]. This feature is [experimental][].
 
 > To track the phased evolution of the agent-support feature, see [Improve
 > support for AI-agent doc consumption #2614][#2614].

docsy.dev/content/en/project/about/changelog.md

@@ -126,20 +126,14 @@ functionality, depending on scope. Prefer narrow, focused PRs where possible.
 For an introduction to this release, see the [0.15.0 release report][]. For the
 full list of changes, see the [0.15.0][] release page.
 
-[**Breaking changes**](#breaking-change):
-
-- **Community and footer link paths** changed for multilingual sites; see
-  [blog][0.15.0-blog-community-footer] ([#2580][]).
-- **Version menu markup and mobile visibility** changed for sites using
-  `params.versions`; see [Version menu entries][0.15.0-blog-version-menu]
-  ([#2557][], [#2586][]).
-- **`card` shortcode rendering** changed for Markdown arguments; breakage risk
-  is low. See [blog][0.15.0-blog-card].
-
 **New**:
 
-- **[Doc-rooted sites][0.15.0-blog-doc-rooted]**: added a documented pattern and
-  example variant for documentation-first sites ([#2563][], [#2587][]).
+- **[Agent support][0.15.0-blog-agent-support]**
+  ([experimental](#experimental)): added Markdown alternate outputs, "View
+  Markdown" links, and `llms.txt` ([#2597][], [#2601][], [#2605][], [#2606][]
+- **[Doc-rooted sites][0.15.0-blog-doc-rooted]**
+  ([experimental](#experimental)): added a documented pattern and example
+  variant for documentation-first sites ([#2563][], [#2587][]).
 - **[Version menu entries][0.15.0-blog-version-menu]**: added support for
   headings, separators, per-entry page-link behavior, and kind-specific styling
   ([#2557][], [#2586][]).
@@ -150,38 +144,29 @@ full list of changes, see the [0.15.0][] release page.
 - Added optional `rel` attribute values for footer `params.links` ([#2576][]);
   see [Community and footer links][0.15.0-blog-community-footer].
 
+[**Breaking changes**](#breaking-change):
+
+- **Community and footer link paths** changed for multilingual sites; see
+  [blog][0.15.0-blog-community-footer] ([#2580][]).
+- **Version menu markup and mobile visibility** changed for sites using
+  `params.versions`; see [Version menu entries][0.15.0-blog-version-menu]
+  ([#2557][], [#2586][]).
+- **`card` shortcode rendering** changed for Markdown arguments; breakage risk
+  is low. See [blog][0.15.0-blog-card].
+
 **Other changes**:
 
 - **Internationalization**: [added and updated
   translations][0.15.0-blog-internationalization].
 - Fixed community/footer links so site-local links no longer open in a new
   browser target ([#2133][], [#2576][]).
 
-[**Experimental**](#experimental):
-
-- **[Agent support][0.15.0-blog-agent-support]**: added Markdown alternate
-  outputs, "View Markdown" links, and `llms.txt` ([#2597][], [#2601][],
-  [#2605][], [#2606][]).
-
-For maintainers:
-
-- Split deployment docs into focused pages and clarified release branch-model
-  docs ([#2556][], [#2572][]).
-- Updated NPM packages and `docsy.dev` tooling, including `hugo-extended`
-  0.157.0 ([#2585][]).
-- Added `siteGetPage` shortcode ([#2586][]) — **internal** to `docsy.dev`; not
-  part of Docsy's [public customization surface](#public) and may change or be
-  removed without notice.
-
 [#2133]: https://github.com/google/docsy/issues/2133
-[#2556]: https://github.com/google/docsy/pull/2556
 [#2557]: https://github.com/google/docsy/pull/2557
 [#2563]: https://github.com/google/docsy/pull/2563
 [#2565]: https://github.com/google/docsy/pull/2565
-[#2572]: https://github.com/google/docsy/pull/2572
 [#2576]: https://github.com/google/docsy/pull/2576
 [#2580]: https://github.com/google/docsy/pull/2580
-[#2585]: https://github.com/google/docsy/pull/2585
 [#2586]: https://github.com/google/docsy/pull/2586
 [#2587]: https://github.com/google/docsy/pull/2587
 [#2597]: https://github.com/google/docsy/pull/2597

docsy.dev/content/en/project/about/maintainer-notes.md

@@ -80,40 +80,56 @@ truth for what the changelog and release blog must cover.
 ## Publishing a release
 
 These notes are WIP for creating a **release** from a local copy of the repo.
-These instructions assume the release is {{% param version %}}, if not adjust
-accordingly.
+These instructions assume the release is:
+
+- **{{% dev-version final %}}**
+
+If not adjust accordingly.
 
 > [!IMPORTANT]
 >
 > Before creating a release, do a [release-prep audit](#release-prep-audit) and
 > use it to drive the changelog and release-blog updates in the next two steps.
 
 1.  **Change directory** to your local Docsy repo.
+    - Expecting final adjustments as you prepare for the release? Create a
+      branch to work from. For example:
+
+      ```sh
+      git checkout -b release-{{% dev-version final %}}-prep
+      # Or you have a local create-branch alias:
+      gcb release-{{% dev-version final %}}-prep
+      ```
+
+    - Serve the site and continue working through these steps from the served
+      version of these notes.
 
-2.  **Create or update a [changelog][] entry** for {{% param version %}}.
+2.  **Create or update a [changelog][] entry** for {{% dev-version final %}}.
     - This step is driven by the [release-prep audit](#release-prep-audit).
     - The section should provide a brief summary of breaking changes using the
       section template at the end of the file.
     - Ensure to remove the UNRELEASED note, if still present.
     - You'll create a new section for the next release in a later step.
 
-3.  **Update the release report blog post** for {{% param version %}}, if any.
+3.  **Update the release report blog post** for {{% dev-version final %}}, if
+    any.
     - Remove draft status.
     - Set `date` (or `lastmod` if already published) to today's date.
 
 4.  Run `npm run fix`.
 
-5.  **Update Docsy version** to {{% param version %}} using the following from a
-    (bash or zsh) terminal.
+5.  **Update Docsy version** to {{% dev-version final %}} using the following
+    from a (bash or zsh) terminal.
     - First set the `VERSION` variable; we use it throughout the steps below.
 
       ```sh
-      VERSION={{% param version %}}
+      VERSION={{% dev-version final %}}
       ```
 
     - Then run the `set:version` script.
 
-      Docsy is probably already at `{{% param version %}}-dev`, so you can run:
+      Docsy is probably already at `{{% dev-version final %}}-dev`, so you can
+      run:
 
       ```sh
       npm run set:version
@@ -143,7 +159,7 @@ accordingly.
     - Commit any changes accumulated from the previous steps using this title:
 
       ```text
-      Release {{% param version %}} preparation
+      Release {{% param tdVersion.latest %}} preparation
       ```
 
     - Create a PR (with version-checks disabled) using the following command
@@ -177,14 +193,14 @@ accordingly.
 
 12. **Ensure** that you're:
     - On the target `$BASE` branch
-    - At the commit that you want to tag as {{% param version %}}
+    - At the commit that you want to tag as {{% param tdVersion.latest %}}
 
-13. **Create the new tag** for {{% param version %}}.
+13. **Create the new tag** for {{% param tdVersion.latest %}}.
     - Set the REL variable to the release version or use the `VERSION` variable
       if you set it in the previous step.
 
       ```sh
-      REL=v${VERSION:-{{% param version %}}}
+      REL=v${VERSION:-{{% param tdVersion.latest %}}}
       echo "REL=$REL"
       ```
 
@@ -253,10 +269,10 @@ accordingly.
 
       ```console
       $ git push-all-remotes $REL
-      + git push origin {{% param version %}}
-      * [new tag]         {{% param version %}} -> {{% param version %}}
-      + git push upstream {{% param version %}}
-      * [new tag]         {{% param version %}} -> {{% param version %}}
+      + git push origin {{% param tdVersion.latest %}}
+      * [new tag]         {{% param tdVersion.latest %}} -> {{% param tdVersion.latest %}}
+      + git push upstream {{% param tdVersion.latest %}}
+      * [new tag]         {{% param tdVersion.latest %}} -> {{% param tdVersion.latest %}}
       ...
       ```
 
@@ -310,15 +326,15 @@ accordingly.
     been updated to the new release.
 
 17. **[Draft a new release][]** using GitHub web; fill in the fields as follows:
-    - Visit [tags][] to find the new release tag {{% param version %}}.
+    - Visit [tags][] to find the new release tag {{% param tdVersion.latest %}}.
 
-    - Select Create a new release from the {{% param version %}} tag dropdown
-      menu
+    - Select Create a new release from the {{% param tdVersion.latest %}} tag
+      dropdown menu
 
     - **Release title**: use the release version.
 
       ```text
-      {{% param version %}}
+      {{% param tdVersion.latest %}}
       ```
 
     - Click **Generate release notes** to get the release details inserted into
@@ -395,7 +411,7 @@ before any further changes are merged into the `main` branch:
 3. **Submit a PR with your changes**, using a title like:
 
    ```text
-   Set version to {{% param version %}}
+   Set version to {{% param tdVersion.latest %}}
    ```
 
 4. **Get PR approved and merged**.

docsy.dev/layouts/_shortcodes/dev-version.html

@@ -1,8 +1,26 @@
+{{/*
+  Returns the development version of Docsy.
+
+  Usage: {{% dev-version [final] %}}
+
+  The development version is read from .Params.version in the page's front
+  matter. If [as-final-version] is true, the final non-dev version is returned,
+  as derived from the dev version. For example, v0.15.0-dev → v0.15.0.
+
+   */ -}}
+
+{{ $finalVersion := eq (.Get 0) "final" -}}
 {{ with $.Site.Params.tdVersion.dev -}}
-  {{ . -}}
-  {{ with $.Site.Params.tdVersion.buildId -}}
-    +{{ replace . "+" "-" -}}
+  {{ $devVersion := . -}}
+  {{ if $finalVersion -}}
+    {{ replace $devVersion "-dev" "" -}}
+  {{ else -}}
+    {{ . -}}
+    {{ with $.Site.Params.tdVersion.buildId -}}
+      +{{ replace . "+" "-" -}}
+    {{ end -}}
   {{ end -}}
+
 {{ else -}}
   {{ with $.Site.Params.version -}}
     {{ replace . " " "_" -}}

layouts/_shortcodes/siteGetPage.html …dev/layouts/_shortcodes/siteGetPage.htmllayouts/_shortcodes/siteGetPage.html renamed to docsy.dev/layouts/_shortcodes/siteGetPage.html layouts/_shortcodes/siteGetPage.html renamed to docsy.dev/layouts/_shortcodes/siteGetPage.html

@@ -1,8 +1,7 @@
 {{- /*
 
-  Returns a property (RelPermalink or Permalink) of the page at the given
-  site-relative path. Internal to docsy.dev test pages; not part of Docsy's
-  public customization surface and may change or be removed without notice.
+  Returns a property of the page at the given site-relative path.
+  Currently used in mock/test homepages.
 
   Usage: {{% siteGetPage "/path/to/page" "RelPermalink" %}}