refactor(docs): version picker left-aligned, Reference dropdown replaced with plain nav links (#177)

The version picker was buried on the right side of the navbar next to
search and theme controls, and the Reference nav entry used a
per-version dropdown while Guide was a plain link — inconsistent and
counterintuitive.

## Changes

### Navbar layout (`_master.tmpl`)
- Removed `ms-auto` from `#version-picker-container` — it was already
before `#navbar` in DOM order, so dropping the margin pushes it left
- Added `flex-grow-1` to `#navbar` so search/theme controls remain
right-aligned

Result: `[Logo] [v1.1 ▾] [Guide] [API Reference] ——— [Search] [Theme]`

### CI toc.yml generation (`publish-documentation.yml`)
- Replaced the "Reference dropdown" step (loop over all versions →
`dropdown: true` + `items:`) with two plain links — `Guide` and `API
Reference` — both pointing to the latest version
- The version picker is now the single source of truth for version
selection

### Nav link version sync (`version-switcher.js`)
- Added `updateNavLinks(version)` — rewrites `href` on all same-origin
navbar `<a>` elements to reflect the active version
  - Uses `new URL(link.href)` for normalised absolute URL handling
  - Same-origin guard eliminates any `javascript:` scheme path
- Version input validated against `/^\d+(\.\d+)*$/` before any DOM
mutation
  - Extracted `VERSION_PATTERN` constant shared across the module
- Called on `window.load` (syncs links to the version in the current
URL) and on version-change before navigation

### Static toc.yml placeholder
- Added `API Reference` entry (pointing to `1.0/`) to reflect the
intended nav structure

Author: Copilot

.github/workflows/publish-documentation.yml

@@ -132,25 +132,16 @@ jobs:
           done
           mv /tmp/api-reference.json api-reference/api-reference.json
 
-      - name: 'Update toc.yml with Reference dropdown'
+      - name: 'Update toc.yml with navigation links'
         shell: bash
         run: |
           latest="${{ steps.discover-versions.outputs.latest }}"
           {
             echo "### YamlMime:TableOfContent"
             echo "- name: Guide"
             echo "  href: ${latest}/guide/introduction.html"
-            echo "- name: Reference"
-            echo "  dropdown: true"
-            echo "  items:"
-            for ver in $(echo "${{ steps.discover-versions.outputs.versions }}" | tr ',' '\n' | sort -Vr); do
-              if [ "$ver" = "$latest" ]; then
-                echo "  - name: v${ver} (latest)"
-              else
-                echo "  - name: v${ver}"
-              fi
-              echo "    href: ${ver}/PolylineAlgorithm.html"
-            done
+            echo "- name: API Reference"
+            echo "  href: ${latest}/PolylineAlgorithm.html"
           } > api-reference/toc.yml
 
       - name: 'Inject latest version and released versions table into index.md'

api-reference/docs-versioning/layout/_master.tmpl

@@ -71,10 +71,10 @@
             <i class="bi bi-three-dots"></i>
           </button>
           <div class="collapse navbar-collapse" id="navpanel">
-            <div id="version-picker-container" class="ms-auto d-flex align-items-center px-2">
+            <div id="version-picker-container" class="d-flex align-items-center px-2">
               <select id="version-picker" class="form-select form-select-sm" style="width:auto" aria-label="Select version"></select>
             </div>
-            <div id="navbar">
+            <div id="navbar" class="flex-grow-1">
               {{#_enableSearch}}
               <form class="search" role="search" id="search">
                 <i class="bi bi-search"></i>

api-reference/docs-versioning/public/version-switcher.js

@@ -16,6 +16,29 @@
     return meta ? meta.getAttribute('content') : './';
   }
 
+  var VERSION_PATTERN = /\/\d+(\.\d+)*\//;
+
+  function updateNavLinks(version) {
+    var navbar = document.getElementById('navbar');
+    if (!navbar || !version) return;
+    if (!/^\d+(\.\d+)*$/.test(version)) return;
+
+    var links = navbar.querySelectorAll('a');
+    links.forEach(function (link) {
+      var absUrl;
+      try {
+        absUrl = new URL(link.href);
+      } catch (e) {
+        return;
+      }
+      if (absUrl.origin !== window.location.origin) return;
+      var newPathname = absUrl.pathname.replace(VERSION_PATTERN, '/' + version + '/');
+      if (newPathname !== absUrl.pathname) {
+        link.setAttribute('href', absUrl.origin + newPathname + absUrl.search + absUrl.hash);
+      }
+    });
+  }
+
   function initVersionPicker(versions, latest) {
     var select = document.getElementById('version-picker');
     if (!select) return;
@@ -42,10 +65,16 @@
       select.insertBefore(placeholder, select.firstChild);
     }
 
+    window.addEventListener('load', function () {
+      updateNavLinks(currentVersion || latest);
+    });
+
     select.addEventListener('change', function () {
       var targetVersion = select.value;
       if (!targetVersion) return;
 
+      updateNavLinks(targetVersion);
+
       var newPathname;
       if (currentVersion && relativePath) {
         newPathname = window.location.pathname.replace(

api-reference/toc.yml

@@ -1,3 +1,5 @@
 ### YamlMime:TableOfContent
 - name: Guide
-  href: guide/
+  href: guide/
+- name: API Reference
+  href: 1.0/