docs: implement versioning system and enhance documentation structure

docs/_ext/static/version_switch.css

@@ -0,0 +1,96 @@
+.docs-floating-switches {
+    position: fixed;
+    left: 24px;
+    bottom: 24px;
+    z-index: 1100;
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 0.75rem;
+    max-width: calc(100vw - 48px);
+}
+
+.docs-floating-switches__item {
+    max-width: min(220px, calc(100vw - 48px));
+}
+
+.docs-version-switch {
+    display: grid;
+    gap: 0.45rem;
+    min-width: 192px;
+    padding: 0.9rem 1rem;
+    border: 1px solid rgba(15, 23, 42, 0.14);
+    border-radius: 14px;
+    background: rgba(255, 255, 255, 0.96);
+    box-shadow: 0 18px 38px rgba(15, 23, 42, 0.16);
+    backdrop-filter: blur(14px);
+}
+
+.docs-version-switch__header {
+    font-size: 0.74rem;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: #5b6472;
+}
+
+.docs-version-switch__control {
+    display: grid;
+    gap: 0.25rem;
+}
+
+.docs-version-switch__label {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+}
+
+.docs-version-switch__select {
+    width: 100%;
+    min-height: 2.4rem;
+    padding: 0 0.85rem;
+    border: 1px solid #c7d2e0;
+    border-radius: 10px;
+    background: #f8fbff;
+    color: #0f172a;
+    font-size: 0.95rem;
+    font-weight: 600;
+}
+
+.docs-version-switch__select:focus {
+    outline: 2px solid rgba(22, 120, 184, 0.22);
+    border-color: #1678b8;
+}
+
+@media (max-width: 768px) {
+    .docs-floating-switches {
+        left: 12px;
+        bottom: 12px;
+        gap: 0.55rem;
+        max-width: calc(100vw - 24px);
+    }
+
+    .docs-floating-switches__item {
+        max-width: calc(100vw - 24px);
+    }
+
+    .docs-version-switch {
+        min-width: 156px;
+        padding: 0.75rem 0.85rem;
+    }
+
+    .docs-version-switch__header {
+        font-size: 0.68rem;
+    }
+
+    .docs-version-switch__select {
+        min-height: 2.2rem;
+        font-size: 0.88rem;
+    }
+}

docs/_ext/static/version_switch.js

@@ -0,0 +1,155 @@
+(function () {
+  function ensureDock() {
+    var dock = document.querySelector("[data-docs-switch-dock]");
+    if (dock) {
+      return dock;
+    }
+
+    dock = document.createElement("div");
+    dock.className = "docs-floating-switches";
+    dock.setAttribute("data-docs-switch-dock", "");
+    document.body.appendChild(dock);
+    return dock;
+  }
+
+  function parseConfig() {
+    var element = document.getElementById("docs-version-data");
+    if (!element) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(element.textContent);
+    } catch (error) {
+      console.error("Failed to parse docs version configuration.", error);
+      return null;
+    }
+  }
+
+  function parseLocation(config) {
+    var segments = window.location.pathname.split("/").filter(Boolean);
+    var langIndex = segments.findIndex(function (segment) {
+      return segment === "en" || segment === "zh";
+    });
+
+    if (langIndex === -1) {
+      return null;
+    }
+
+    var language = segments[langIndex];
+    var isVersioned = langIndex >= 2 && segments[langIndex - 2] === "versions";
+    var versionSlug = isVersioned ? segments[langIndex - 1] : config.latest_slug;
+    // Keep the project-pages prefix (for example /<repo>/...) when the
+    // current page is served from the latest alias path /<repo>/<lang>/...
+    var baseSegments = isVersioned ? segments.slice(0, langIndex - 2) : segments.slice(0, langIndex);
+    var relativeSegments = segments.slice(langIndex + 1);
+
+    if (!relativeSegments.length) {
+      relativeSegments = ["index.html"];
+    }
+
+    return {
+      baseSegments: baseSegments,
+      language: language,
+      relativeSegments: relativeSegments,
+      versionSlug: versionSlug,
+    };
+  }
+
+  function buildPath(baseSegments, versionSlug, latestSlug, language, relativeSegments) {
+    var segments = baseSegments.slice();
+    if (versionSlug !== latestSlug) {
+      segments.push("versions", versionSlug);
+    }
+    segments.push(language);
+    segments = segments.concat(relativeSegments);
+    return "/" + segments.join("/");
+  }
+
+  function buildRootPath(baseSegments, versionSlug, latestSlug, language) {
+    var segments = baseSegments.slice();
+    if (versionSlug !== latestSlug) {
+      segments.push("versions", versionSlug);
+    }
+    segments.push(language, "index.html");
+    return "/" + segments.join("/");
+  }
+
+  function renderOptions(select, config, currentSlug) {
+    select.innerHTML = "";
+
+    config.versions.forEach(function (version) {
+      var option = document.createElement("option");
+      option.value = version.slug;
+      option.textContent = version.label;
+      option.selected = version.slug === currentSlug;
+      select.appendChild(option);
+    });
+  }
+
+  function canUseHeadRequest() {
+    return window.location.protocol === "http:" || window.location.protocol === "https:";
+  }
+
+  function pageExists(url) {
+    if (!canUseHeadRequest()) {
+      return Promise.resolve(true);
+    }
+
+    return fetch(url, {
+      method: "HEAD",
+      cache: "no-store",
+    })
+      .then(function (response) {
+        return response.ok;
+      })
+      .catch(function () {
+        return false;
+      });
+  }
+
+  document.addEventListener("DOMContentLoaded", function () {
+    var config = parseConfig();
+    var widget = document.querySelector("[data-docs-version-switch]");
+    var select = document.getElementById("docs-version-select");
+
+    if (!config || !widget || !select || !config.versions || !config.versions.length) {
+      return;
+    }
+
+    ensureDock().appendChild(widget);
+
+    var locationInfo = parseLocation(config);
+    if (!locationInfo) {
+      widget.hidden = true;
+      return;
+    }
+
+    renderOptions(select, config, locationInfo.versionSlug);
+
+    select.addEventListener("change", function (event) {
+      var nextSlug = event.target.value;
+      if (!nextSlug || nextSlug === locationInfo.versionSlug) {
+        return;
+      }
+
+      var targetUrl = buildPath(
+        locationInfo.baseSegments,
+        nextSlug,
+        config.latest_slug,
+        locationInfo.language,
+        locationInfo.relativeSegments,
+      );
+      var fallbackUrl = buildRootPath(
+        locationInfo.baseSegments,
+        nextSlug,
+        config.latest_slug,
+        locationInfo.language,
+      );
+
+      pageExists(targetUrl).then(function (exists) {
+        window.location.href = exists ? targetUrl : fallbackUrl;
+      });
+    });
+  });
+})();