From 2fe2c05e734616752cb269fac2456ad3f6a37813 Mon Sep 17 00:00:00 2001
From: Kevin Liu <kevin.jq.liu@gmail.com>
Date: Wed, 20 May 2026 16:22:22 -0700
Subject: [PATCH] fix version alias

---
 site/hooks/version_alias.py | 51 +++++++++++++++++++++++++++++++++++++
 site/mkdocs-dev.yml         |  2 +-
 site/mkdocs.yml             |  4 +++
 3 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 site/hooks/version_alias.py

diff --git a/site/hooks/version_alias.py b/site/hooks/version_alias.py
new file mode 100644
index 000000000000..e980aefb80cf
--- /dev/null
+++ b/site/hooks/version_alias.py
@@ -0,0 +1,51 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+MkDocs hook: version URL alias.
+
+Creates a symlink so that /docs/<icebergVersion>/ resolves to /docs/latest/.
+This allows version-specific URLs (e.g. /docs/1.11.0/) to work without
+duplicating the navigation entry for the latest version.
+"""
+
+import logging
+from pathlib import Path
+
+log = logging.getLogger("mkdocs.hooks.version_alias")
+
+
+def on_post_build(config):
+    version = config["extra"].get("icebergVersion")
+    if not version:
+        return
+
+    site_dir = Path(config["site_dir"])
+    latest_dir = site_dir / "docs" / "latest"
+    version_link = site_dir / "docs" / version
+
+    if not latest_dir.exists():
+        log.warning("docs/latest not found in site output; skipping version alias")
+        return
+
+    # Remove stale symlink if the version changed between rebuilds
+    if version_link.is_symlink():
+        version_link.unlink()
+
+    if not version_link.exists():
+        version_link.symlink_to("latest")
+        log.info("Created version alias: docs/%s -> docs/latest", version)
diff --git a/site/mkdocs-dev.yml b/site/mkdocs-dev.yml
index b5b98c983056..f8d4d71bf316 100644
--- a/site/mkdocs-dev.yml
+++ b/site/mkdocs-dev.yml
@@ -30,7 +30,7 @@ nav:
   - Docs:
     - Java:
       # First entry determines the default landing page for the Docs tab.
-      - Latest (1.10.2): '!include versioned-docs/latest/mkdocs.yml'
+      - Latest (1.11.0): '!include versioned-docs/latest/mkdocs.yml'
       - Nightly: '!include versioned-docs/nightly/mkdocs.yml'
     - Other Implementations:
       - Python: https://py.iceberg.apache.org/
diff --git a/site/mkdocs.yml b/site/mkdocs.yml
index 47da052fc511..e8d11687d6ee 100644
--- a/site/mkdocs.yml
+++ b/site/mkdocs.yml
@@ -47,6 +47,10 @@ theme:
     - content.code.copy
     - content.code.annotate
 
+hooks:
+  # Symlinks docs/<version>/ to docs/latest/ so both URLs resolve.
+  - hooks/version_alias.py
+
 plugins:
   - search
   - blog: