Update version+variant menu, add siteGetPage shortcode, add tdVersion struct, and more

assets/scss/td/_nav.scss

@@ -162,6 +162,12 @@ $td-link-underline-offsets: (
           content: ' (latest)';
         }
       }
+
+      &-next {
+        &::after {
+          content: ' (next)';
+        }
+      }
     }
   }
 

docsy.dev/config/_default/params.yaml

@@ -6,31 +6,26 @@
 # version:
 #   status: archived # Then fetch include
 
-version: &docsyVersion 0.14.4-dev
-tdBuildId: 022-over-main-6884d94e
-versionLatest: &versionLatest v0.14.3
-version_menu: *docsyVersion
+tdVersion:
+  latest: &tdLatestVers v0.14.3
+  dev: &tdDevVers v0.14.4-dev
+  buildId: &tdBuildId 023-over-main-3bcb7385
+
+version: *tdDevVers
+version_menu: *tdDevVers
 version_menu_pagelinks: true
 versions:
-  # - name: '**About**'
-  #   url: /project
-  #   pagelinks: false
-  # - name: ---
   - name: '**Versions**'
-  - name: Next
-    version: *docsyVersion
-    # TODO: use https://next.docsy.dev once it's available
-    url: https://main--docsydocs.netlify.app
-  - version: *versionLatest
-    url: https://www.docsy.dev
+  - version: *tdDevVers
+    # kind: next
+    pagelinks: true
+    url: https://main--docsydocs.netlify.app # TODO: use next.docsy.dev once available
+  - version: *tdLatestVers
     kind: latest
+    url: https://www.docsy.dev
   - name: ---
   - name: '**Variant**'
-  - name: Doc-rooted
-    url: https://doc-rooted--docsydocs.netlify.app
-    # TODO: implement /docs/* redirects for doc-rooted site, then drop pagelinks:false
-    pagelinks: false
+  - name: Doc-rooted (experimental)
     kind: home
-  # - name: Goldydocs
-  #   url: https://example.docsy.dev
-  #   pagelinks: false
+    pagelinks: false # TODO: drop this once /docs/* redirects are implemented
+    url: https://doc-rooted--docsydocs.netlify.app

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

@@ -1,13 +1,26 @@
 # cSpell:ignore pagelinks
 
-version: &docsyVersion 0.14.3
-version_menu: *docsyVersion
+tdVersion:
+  latest: &tdLatestVers v0.14.3
+  dev: &tdDevVers v0.14.4-dev
+  buildId: &tdBuildId 023-over-main-3bcb7385
+
+version: &tdDocRootedVers Doc-rooted of Next
+version_menu: *tdLatestVers
+version_menu_pagelinks: false
 versions:
+  - name: '**Versions**'
   - name: Next
-    kind: next
-    url: https://main--docsydocs.netlify.app/
-    pagelinks: false
-  - version: *docsyVersion
+    version: *tdDevVers
+    # kind: next
+    url: https://main--docsydocs.netlify.app
+  - version: *tdLatestVers
     kind: latest
     url: https://www.docsy.dev
-    pagelinks: false
+  - name: ---
+  - name: '**Variant**'
+  - name: Doc-rooted (experimental)
+    version: *tdDocRootedVers
+    kind: home
+    pagelinks: false # TODO: drop this once /docs/* redirects are implemented
+    url: https://doc-rooted--docsydocs.netlify.app

docsy.dev/config/production/params.yaml

@@ -1,13 +1,18 @@
 # cSpell:ignore pagelinks
 
-version: &docsyVersion 0.14.3
-version_menu: *docsyVersion
+tdVersion:
+  latest: &tdLatestVers v0.14.3
+  dev: &tdDevVers v0.14.4-dev
+  buildId: &tdBuildId 023-over-main-3bcb7385
+
+version: *tdLatestVers
+version_menu: *tdLatestVers
 versions:
+  - name: '**Versions**'
   - name: Next
-    kind: next
-    url: https://main--docsydocs.netlify.app/
-    pagelinks: true
-  - version: *docsyVersion
+    version: *tdDevVers
+    # kind: next
+    url: https://main--docsydocs.netlify.app
+  - version: *tdLatestVers
     kind: latest
     url: https://www.docsy.dev
-    pagelinks: true

docsy.dev/content/en/docs/get-started/other-options.md

@@ -165,7 +165,7 @@ your project's root directory:
     ```sh
     git submodule add https://github.com/google/docsy.git themes/docsy
     cd themes/docsy
-    git checkout v{{% param version %}}
+    git checkout {{% param version %}}
     ```
 
     To work from the development version of Docsy (_not recommended_), run the
@@ -229,12 +229,12 @@ maintain your own copy of the theme directly, or your deployment choice requires
 you to include a copy of the theme in your repository), you can clone the theme
 into your project's `themes` subdirectory.
 
-To clone Docsy at v{{% param version %}} into your project's `themes` folder,
-run the following commands from your project's root directory:
+To clone Docsy at {{% param version %}} into your project's `themes` folder, run
+the following commands from your project's root directory:
 
 ```sh
 cd themes
-git clone -b v{{% param version %}} https://github.com/google/docsy
+git clone -b {{% param version %}} https://github.com/google/docsy
 cd docsy
 npm install
 ```
@@ -243,7 +243,7 @@ npm install
 
 To work from the development version of Docsy (not recommended unless, for
 example, you plan to upstream changes to Docsy), omit the
-`-b v{{% param version %}}` argument from the clone command above.
+`-b {{% param version %}}` argument from the clone command above.
 
 Then consider setting up an NPM [prepare][] script, as documented in Option 1.
 

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

@@ -28,12 +28,6 @@ accordingly.
 
 4.  Run `npm run fix`.
 
-    > [!NOTE]
-    >
-    > This command might update the version in `package.json` via `fix:version`,
-    > but you can ignore this change since you'll be setting the version
-    > explicitly in the next step.
-
 5.  **Update Docsy version** to {{% param version %}} using the following from a
     (bash or zsh) terminal.
     - First set the `VERSION` variable; we use it throughout the steps below.
@@ -184,10 +178,10 @@ accordingly.
 
       ```console
       $ git push-all-remotes $REL
-      + git push origin v{{% param version %}}
-      * [new tag]         v{{% param version %}} -> v{{% param version %}}
-      + git push upstream v{{% param version %}}
-      * [new tag]         v{{% param version %}} -> v{{% param version %}}
+      + git push origin {{% param version %}}
+      * [new tag]         {{% param version %}} -> {{% param version %}}
+      + git push upstream {{% param version %}}
+      * [new tag]         {{% param version %}} -> {{% param version %}}
       ...
       ```
 
@@ -241,15 +235,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 v{{% param version %}}.
+    - Visit [tags][] to find the new release tag {{% param version %}}.
 
-    - Select Create a new release from the v{{% param version %}} tag dropdown
+    - Select Create a new release from the {{% param version %}} tag dropdown
       menu
 
     - **Release title**: use the release version.
 
       ```text
-      v{{% param version %}}
+      {{% param version %}}
       ```
 
     - Click **Generate release notes** to get the release details inserted into
@@ -299,20 +293,20 @@ with the following modifications:
 
 ## Post Docsy-release followup
 
-Assuming that both the Docsy and Docsy-example releases v{{% param version %}}
+Assuming that both the Docsy and Docsy-example releases {{% param version %}}
 have been successfully deployed, and that at least one other project has been
 successfully tested with the new release, then perform the following actions
 before any further changes are merged into the `main` branch:
 
 1. Update the package version to a dev ID for Docsy and Docsy-example:
 
    ```console
-   $ npm run -s fix:version
+   $ npm run -s set:version:git-info
    ✓ Updated package.json version: 0.14.3 → 0.14.3-dev+003-over-main-cf4f514b
    ✓ Updated docsy.dev/config/_default/params.yaml version: 0.14.3 → 0.14.3-dev
    ✓ Updated docsy.dev/config/_default/params.yaml tdBuildId: (none) → 003-over-main-cf4f514b
    ...
-   $ npm run -s fix:version:example
+   $ npm run -s set:version:example:git-info
    ...
    ```
 
@@ -333,7 +327,7 @@ before any further changes are merged into the `main` branch:
 
 ## Release helper scripts
 
-- NPM scripts: `fix:version`, `fix:version:example`, and `set:version`.
+- NPM scripts: `set:version` and `set:version:*`
 - `scripts/get-build-id.sh`: Generates build ID from git describe (empty on
   tags).
 - `scripts/set-package-version/index.mjs`: Low-level version manager. See script

docsy.dev/content/en/tests/blocks-cover/color-gradient/index.md

@@ -17,7 +17,8 @@ description: A Hugo theme for creating great technical documentation sites
 
 <!-- prettier-ignore -->
 <div class="td-cta-buttons my-5">
-  <a {{% _param btn-lg primary %}} href="/docs/get-started/">
+  <a {{% _param btn-lg primary %}}
+     href='{{% siteGetPage "/docs/get-started" RelPermalink %}}'>
     Get started
   </a>
   <a {{% _param btn-lg secondary %}}

docsy.dev/content/en/tests/blocks-cover/height-auto/index.md

@@ -17,7 +17,8 @@ description: A Hugo theme for creating great technical documentation sites
 
 <!-- prettier-ignore -->
 <div class="td-cta-buttons my-5">
-  <a {{% _param btn-lg primary %}} href="/docs/get-started/">
+  <a {{% _param btn-lg primary %}}
+     href='{{% siteGetPage "/docs/get-started" RelPermalink %}}'>
     Get started
   </a>
   <a {{% _param btn-lg secondary %}}

docsy.dev/content/en/tests/blocks-cover/height-full/index.md

@@ -17,7 +17,8 @@ description: A Hugo theme for creating great technical documentation sites
 
 <!-- prettier-ignore -->
 <div class="td-cta-buttons my-5">
-  <a {{% _param btn-lg primary %}} href="/docs/get-started/">
+  <a {{% _param btn-lg primary %}}
+     href='{{% siteGetPage "/docs/get-started" RelPermalink %}}'>
     Get started
   </a>
   <a {{% _param btn-lg secondary %}}

docsy.dev/content/en/tests/blocks-cover/height-min/index.md

@@ -19,7 +19,8 @@ params:
 
 <!-- prettier-ignore -->
 <div class="td-cta-buttons my-5">
-  <a {{% _param btn-lg primary %}} href="/docs/get-started/">
+  <a {{% _param btn-lg primary %}}
+     href='{{% siteGetPage "/docs/get-started" RelPermalink %}}'>
     Get started
   </a>
   <a {{% _param btn-lg secondary %}}

docsy.dev/layouts/_shortcodes/release-summary.md

@@ -7,6 +7,7 @@
 */ -}}
 
 {{ $version := $.Page.Param "version" | string -}}
+{{ $version = strings.TrimPrefix "v" $version -}}
 {{ $isDevVersion := strings.Contains $version "-dev" -}}
 {{ if not $version -}}
   {{ errorf "%s: shortcode 'release-summary': version parameter not found in page or site params" .Position -}}
@@ -33,18 +34,30 @@
   {{ end -}}
 {{ end -}}
 
-{{ if and (not $blogPage) (not $isDevVersion) -}}
-  {{ errorf "%s: shortcode 'release-summary': blog post not found for version %q (tried %q) during years: %q"
-      .Position $version (delimit (slice $version $versionForBlog) ", ") (delimit $years ", ") -}}
+{{ $changelogUrlFragment := add "#" $version -}}
+{{ $errorOnMissingBlogPost := and (not $blogPage) (not $isDevVersion) -}}
+{{ if $errorOnMissingBlogPost -}}
+  {{ if false -}}
+    {{ errorf "%s: shortcode 'release-summary': blog post not found for version %q (tried %q) during years: %q"
+        .Position $version (delimit (slice $version $versionForBlog) ", ") (delimit $years ", ") -}}
+  {{ else -}}
+    {{ $changelogUrlFragment = "" -}}
+  {{ end -}}
 {{ end -}}
 
-{{ $changelogURL := printf "/project/about/changelog/#v%s" $version -}}
+{{ $changelogURL := printf "/project/about/changelog/%s" $changelogUrlFragment -}}
 {{ $productionURL := .Site.Params.productionURL -}}
 
 ## Release summary
 
-- [{{ $blogPage.Title }}][blog-post]
+- [{{ $blogPage.Title | default "Blog" }}][blog]
 - [Changelog v{{ $version }}][changelog] entry
 
-[blog-post]: <{{ $productionURL }}{{ $blogPage.RelPermalink }}>
+{{ if and (not $blogPage) (not $isDevVersion) -}}
+<!--
+  {{ printf "WARNING: shortcode 'release-summary': blog post not found for\n  version %q (tried %q) during years: %q\n"
+       $version (delimit (slice $version $versionForBlog) ", ") (delimit $years ", ") -}}
+-->
+{{ end }}
+[blog]: <{{ $productionURL }}{{ $blogPage.RelPermalink | default "/blog/" }}>
 [changelog]: <{{ $productionURL }}{{ $changelogURL }}>

layouts/_shortcodes/siteGetPage.html

@@ -0,0 +1,14 @@
+{{ $path := .Get 0 -}}
+{{ $propertyName := .Get 1 -}}
+{{ if or (not $path) (not $propertyName) -}}
+  {{ errorf "shortcode 'siteGetPage': path and property name are required" .Position -}}
+{{ end -}}
+{{ with site.GetPage $path -}}
+  {{ if eq $propertyName "RelPermalink" -}}
+    {{ .RelPermalink }}
+  {{ else if eq $propertyName "Permalink" -}}
+    {{ .Permalink }}
+  {{ else -}}
+    {{ errorf "shortcode 'siteGetPage': unsupported or unknown property name %q" $propertyName .Position -}}
+  {{ end -}}
+{{ end -}}

package.json

@@ -1,13 +1,14 @@
 {
   "name": "docsy",
-  "version": "0.14.4-dev+022-over-main-6884d94e",
+  "version": "0.14.4-dev+023-over-main-3bcb7385",
   "repository": "github:google/docsy",
   "homepage": "https://www.docsy.dev",
   "license": "Apache-2.0",
   "workspaces": [
     "docsy.dev"
   ],
   "scripts": {
+    "__spv": "node scripts/set-package-version/index.mjs",
     "_cd:docsy.dev": "cd docsy.dev &&",
     "_check:format": "npx prettier --check assets *.md i18n scripts tasks",
     "_check:links": "npm run _cd:docsy.dev -- npm run _check:links",
@@ -22,7 +23,8 @@
     "_prepare": "npm run _cp:bs-rfs && npm run _prepare:scrollspy-patch && npm run _refresh-forward-sass-var && npm run _gen-chroma-styles && npm run get:hugo-modules",
     "_refresh-forward-sass-var": "bash -c scripts/refresh-sass-variables.pl",
     "_serve": "npm run _cd:docsy.dev -- npm run _serve --",
-    "_spv": "node scripts/set-package-version/index.mjs",
+    "_spv:example": "echo TBC - npm run -s __spv docsy.dev/config/example/params.yaml --",
+    "_spv": "npm run -s __spv docsy.dev/config/*/params.yaml --",
     "build": "npm run _cd:docsy.dev -- npm run build --",
     "cd:docsy.dev": "echo 'Running in docsy.dev...'; npm run _cd:docsy.dev -- npm run",
     "check:format": "npm list prettier && npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
@@ -38,10 +40,8 @@
     "fix:format:diff": "npm run fix:format",
     "fix:format": "npm run -s _check:format -- --write && echo && npm run -s cd:docsy.dev fix:format",
     "fix:markdown": "npm run check:markdown -- --fix",
-    "fix:version:example": "npm run set:version:example -- -c ../hugo.yaml --version \"$(scripts/get-build-id.sh)\"",
-    "fix:version": "npm run -s _spv -- --version \"$(scripts/get-build-id.sh)\"",
-    "fix-for-test": "npm run fix:format && npm run fix:markdown && echo 'Skipping fix:version' && npm run cd:docsy.dev fix",
-    "fix": "npm run fix:format && npm run fix:markdown && npm run fix:version && npm run cd:docsy.dev fix",
+    "fix-for-test": "npm run fix:format && npm run fix:markdown && npm run cd:docsy.dev fix",
+    "fix": "npm run fix:format && npm run fix:markdown && npm run cd:docsy.dev fix",
     "get:hugo-modules": "node scripts/getHugoModules/index.mjs",
     "post-update": "echo; echo 'IMPORTANT! Run the following in case the ScrollSpy patch needs to be updated:\n  npm run _prepare'; echo",
     "postinstall": "npm run _mkdir:hugo-mod",
@@ -50,8 +50,10 @@
     "prune:refcache": "npm run _cd:docsy.dev -- npm run prune:refcache --",
     "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ",
     "serve": "npm run _cd:docsy.dev -- npm run serve --",
-    "set:version:example": "cd ../docsy-example && node ../docsy/scripts/set-package-version/index.mjs",
-    "set:version": "npm run -s _spv -- -c config/production/params.yaml && npm run -s _spv && npm run -s fix:version",
+    "set:version:example:git-info": "echo FIXME - npm run set:version:example -- -c ../hugo.yaml --version \"$(scripts/get-build-id.sh)\"",
+    "set:version:example": "echo FIXME - 'cd ../docsy-example && node ../docsy/scripts/set-package-version/index.mjs'",
+    "set:version:git-info": "npm run -s _spv -- --version \"$(scripts/get-build-id.sh)\"",
+    "set:version": "npm run -s _spv --",
     "test:tooling": "node --test 'scripts/**/*.test.mjs'",
     "test:website": "npm run cd:docsy.dev test",
     "test": "npm run fix-and-test",