Emit pages.xml — a simplified fallback sitemap

mkdocs-static-i18n adds xhtml:link hreflang alternates to
sitemap.xml. Some Google Search Console fetches fail on that variant
(known issue with GSC + GitHub Pages + bilingual sitemaps), and once
GSC caches the failure it doesn't re-test for days.

pages.xml is a flat urlset with the same 40 URLs, no alternates,
no namespaces beyond the base sitemap protocol. Lets us re-submit
to GSC under a fresh name and bypass the cached failure.

Author: bilouro

mkdocs_hooks.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import logging
+import xml.etree.ElementTree as ET
+from pathlib import Path
 from typing import Any
 
 
@@ -14,3 +16,45 @@ def on_config(config: Any, **kwargs: Any) -> Any:
     # Silence only that logger; every other warning still fails strict mode.
     logging.getLogger("mkdocs.plugins.mkdocs_autorefs").setLevel(logging.ERROR)
     return config
+
+
+def on_post_build(config: Any, **kwargs: Any) -> None:
+    """Emit a simplified fallback sitemap at ``pages.xml``.
+
+    The standard ``sitemap.xml`` generated by mkdocs-static-i18n includes
+    ``xhtml:link`` alternates for the bilingual setup. Google Search Console
+    sometimes fails to fetch that sitemap on GitHub Pages (cached failure,
+    hreflang quirks). This hook produces a second, plain ``urlset`` sitemap
+    under a different filename so the GSC can be re-submitted without
+    hitting its failure cache.
+    """
+    site_dir = Path(config["site_dir"])
+    src = site_dir / "sitemap.xml"
+    if not src.exists():
+        return
+
+    ns = {"s": "http://www.sitemaps.org/schemas/sitemap/0.9"}
+    tree = ET.parse(src)
+    root = tree.getroot()
+
+    lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    ]
+    for url in root.findall("s:url", ns):
+        loc = url.find("s:loc", ns)
+        lastmod = url.find("s:lastmod", ns)
+        changefreq = url.find("s:changefreq", ns)
+        if loc is None or loc.text is None:
+            continue
+        lines.append("  <url>")
+        lines.append(f"    <loc>{loc.text}</loc>")
+        if lastmod is not None and lastmod.text:
+            lines.append(f"    <lastmod>{lastmod.text}</lastmod>")
+        if changefreq is not None and changefreq.text:
+            lines.append(f"    <changefreq>{changefreq.text}</changefreq>")
+        lines.append("  </url>")
+    lines.append("</urlset>")
+
+    out = site_dir / "pages.xml"
+    out.write_text("\n".join(lines) + "\n", encoding="utf-8")