feat(docs): add versioning support for documentation

- Introduced versioning for documentation by creating a new `versions.js` file that holds available versions.
- Updated `docs.js` to dynamically load documentation based on the selected version from the URL query parameter.
- Enhanced the documentation conversion tool to accept a version argument, generating versioned output files and updating `versions.js` accordingly.
- Improved user experience by adding a version selector in the documentation viewer.

Author: jmjoy

css/docs.css

@@ -2,6 +2,43 @@
 .docs-layout {
   display: flex;
   min-height: calc(100vh - var(--header-height));
+  max-width: 1440px;
+  margin: 0 auto;
+  width: 100%;
+}
+
+/* ===== Sidebar Version Selector ===== */
+.sidebar-version-selector {
+  padding: 12px 20px 16px;
+  border-bottom: 1px solid var(--color-border-light);
+  margin-bottom: 8px;
+}
+
+.sidebar-version-selector label {
+  display: block;
+  font-size: 0.72rem;
+  font-weight: 600;
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  margin-bottom: 6px;
+}
+
+.sidebar-version-selector select {
+  width: 100%;
+  padding: 6px 10px;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-sm);
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-size: 0.88rem;
+  font-family: inherit;
+  cursor: pointer;
+}
+
+.sidebar-version-selector select:focus {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 1px;
 }
 
 /* ===== Sidebar ===== */
@@ -116,6 +153,7 @@
   min-width: 0;
   padding: 40px 48px;
   max-width: 900px;
+  margin: 0 auto;
   counter-reset: doc-ol;
 }
 

docs.html

@@ -39,8 +39,13 @@
   <div class="docs-layout">
     <!-- ===== Sidebar ===== -->
     <aside class="docs-sidebar" id="docsSidebar">
+      <!-- Version selector (hidden until versions.js provides data) -->
+      <div class="sidebar-version-selector" id="versionWrapper" style="display:none">
+        <label for="versionSelect">Version</label>
+        <select id="versionSelect"></select>
+      </div>
       <ul class="sidebar-nav" id="sidebarNav">
-        <!-- Populated by docs.js from docs-data.js -->
+        <!-- Populated by docs.js -->
       </ul>
     </aside>
 
@@ -67,7 +72,7 @@
     <p>&copy; 2022–2026 PHPER Framework Team · Licensed under <a href="https://github.com/phper-framework/phper/blob/master/LICENSE" target="_blank" rel="noopener">MulanPSL-2.0</a></p>
   </footer>
 
-  <script src="docs/docs-data.js"></script>
+  <script src="docs/versions.js"></script>
   <script src="js/docs.js"></script>
 </body>
 </html>

docs/0.16/docs-data.js

@@ -0,0 +1,2 @@
+// Auto-generated by tools/convert-docs.py — DO NOT EDIT
+window.DOCS_VERSIONS = ["0.17", "0.16"];

docs/0.17/docs-data.js

@@ -1,17 +1,70 @@
 // PHPER Docs — Documentation viewer with sidebar navigation
-// Reads DOCS_DATA from docs/docs-data.js and renders documentation pages
+// Supports versioned docs data: docs/{version}/docs-data.js
+// Falls back to docs/docs-data.js when no version is specified
 
-document.addEventListener('DOMContentLoaded', () => {
+/** Return the currently selected version from URL query param, or first in DOCS_VERSIONS. */
+function getVersion() {
+  const params = new URLSearchParams(window.location.search);
+  const v = params.get('version');
+  if (v) return v;
+  if (window.DOCS_VERSIONS && DOCS_VERSIONS.length > 0) return DOCS_VERSIONS[0];
+  return null;
+}
+
+/** Dynamically append a <script> and resolve when loaded. */
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    const s = document.createElement('script');
+    s.src = src;
+    s.onload = resolve;
+    s.onerror = reject;
+    document.head.appendChild(s);
+  });
+}
+
+document.addEventListener('DOMContentLoaded', async () => {
   const sidebarNav = document.getElementById('sidebarNav');
   const docsContent = document.getElementById('docsContent');
   const sidebarToggle = document.getElementById('sidebarToggle');
   const sidebar = document.getElementById('docsSidebar');
   const overlay = document.getElementById('sidebarOverlay');
+  const versionSelect = document.getElementById('versionSelect');
+  const versionWrapper = document.getElementById('versionWrapper');
+
+  // ── Load versioned (or default) docs data ──────────────────────
+  const version = getVersion();
+  try {
+    if (version) {
+      await loadScript(`docs/${version}/docs-data.js`);
+    } else {
+      await loadScript('docs/docs-data.js');
+    }
+  } catch (_) {
+    // Try fallback
+    try { await loadScript('docs/docs-data.js'); } catch (e2) { /* ignore */ }
+  }
+
+  // ── Populate version selector ───────────────────────────────────
+  if (versionSelect && window.DOCS_VERSIONS && DOCS_VERSIONS.length > 0) {
+    versionWrapper.style.display = '';
+    DOCS_VERSIONS.forEach((v) => {
+      const opt = document.createElement('option');
+      opt.value = v;
+      opt.textContent = v;
+      if (v === version) opt.selected = true;
+      versionSelect.appendChild(opt);
+    });
+    versionSelect.addEventListener('change', () => {
+      const url = new URL(window.location.href);
+      url.searchParams.set('version', versionSelect.value);
+      window.location.href = url.toString();
+    });
+  }
 
   if (!window.DOCS_DATA || !DOCS_DATA.length) {
     docsContent.innerHTML =
       '<h1>Documentation</h1><p>No documentation data found. Run the conversion tool first:</p>' +
-      '<pre><code>python3 tools/convert-docs.py ../phper/phper-doc/doc</code></pre>';
+      '<pre><code>python3 tools/convert-docs.py --version 0.5.0 ../phper/phper-doc/doc</code></pre>';
     return;
   }
 

docs/versions.js

@@ -4,21 +4,23 @@
 PHPER GitHub Pages site.
 
 Usage:
-    python3 tools/convert-docs.py [PHPER_DOC_DIR] [OUTPUT_FILE]
+    python3 tools/convert-docs.py [PHPER_DOC_DIR] [--version VERSION] [--output OUTPUT]
 
     PHPER_DOC_DIR  Path to phper/phper-doc/doc directory
                    (default: ../phper/phper-doc/doc)
-    OUTPUT_FILE    Output JS file path
-                   (default: docs/docs-data.js)
+    --version, -v  Version string (e.g. 0.5.0). Output goes to
+                   docs/VERSION/docs-data.js and docs/versions.js is updated.
+    --output, -o   Override output JS file path.
 
-The tool scans the phper-doc directory structure, reads each index.md,
-converts Markdown to HTML, and writes a single JS data file that the
-docs page can consume.
+When --version is supplied the generated file is placed under a versioned
+subdirectory (docs/VERSION/docs-data.js) and docs/versions.js is kept in sync
+so the docs page can offer a version dropdown selector.
 
 Requirements:
     pip install markdown pygments
 """
 
+import argparse
 import json
 import os
 import re
@@ -216,21 +218,82 @@ def write_docs_data(sections: list, output_path: str) -> None:
     print(f"  {len(sections)} sections, {page_count} total pages")
 
 
+def update_versions_js(version: str, site_root: Path) -> None:
+    """Add *version* to docs/versions.js (newest first), creating the file if needed."""
+    versions_path = site_root / "docs" / "versions.js"
+
+    existing: list = []
+    if versions_path.exists():
+        content = versions_path.read_text(encoding="utf-8")
+        match = re.search(r"window\.DOCS_VERSIONS\s*=\s*(\[.*?\])", content, re.DOTALL)
+        if match:
+            try:
+                existing = json.loads(match.group(1))
+            except json.JSONDecodeError:
+                existing = []
+
+    if version not in existing:
+        existing.insert(0, version)
+
+    js_content = (
+        "// Auto-generated by tools/convert-docs.py — DO NOT EDIT\n"
+        f"window.DOCS_VERSIONS = {json.dumps(existing)};\n"
+    )
+    with open(versions_path, "w", encoding="utf-8") as f:
+        f.write(js_content)
+
+    print(f"✓ Updated {versions_path}  versions: {existing}")
+
+
 def main():
     # Determine base directory of this script for default paths
     script_dir = Path(__file__).resolve().parent
     site_root = script_dir.parent
 
     # Default phper-doc path: assume phper repo is sibling
     default_doc_dir = site_root.parent / "phper" / "phper-doc" / "doc"
-    default_output = site_root / "docs" / "docs-data.js"
 
-    doc_dir = sys.argv[1] if len(sys.argv) > 1 else str(default_doc_dir)
-    output = sys.argv[2] if len(sys.argv) > 2 else str(default_output)
+    parser = argparse.ArgumentParser(
+        description="Convert phper-doc markdown files into docs-data.js"
+    )
+    parser.add_argument(
+        "doc_dir",
+        nargs="?",
+        default=str(default_doc_dir),
+        metavar="PHPER_DOC_DIR",
+        help=f"Path to phper/phper-doc/doc directory (default: {default_doc_dir})",
+    )
+    parser.add_argument(
+        "--version",
+        "-v",
+        default=None,
+        metavar="VERSION",
+        help="Version string, e.g. 0.5.0. Output goes to docs/VERSION/docs-data.js "
+             "and docs/versions.js is updated.",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        default=None,
+        metavar="OUTPUT_FILE",
+        help="Override the output JS file path.",
+    )
 
-    print(f"PHPER Documentation Converter")
+    args = parser.parse_args()
+    doc_dir = args.doc_dir
+
+    if args.output:
+        output = args.output
+    elif args.version:
+        output = str(site_root / "docs" / args.version / "docs-data.js")
+    else:
+        output = str(site_root / "docs" / "docs-data.js")
+
+    print("PHPER Documentation Converter")
     print(f"  Source:  {doc_dir}")
     print(f"  Output:  {output}")
+    if args.version:
+        print(f"  Version: {args.version}")
     print()
 
     sections = scan_doc_dir(doc_dir)
@@ -239,6 +302,11 @@ def main():
         sys.exit(1)
 
     write_docs_data(sections, output)
+
+    # Keep versions.js in sync when a version was supplied
+    if args.version:
+        update_versions_js(args.version, site_root)
+
     print("\nDone! Open docs.html to view the documentation.")