website: migrate from mkdocs to zensical

Replace mkdocs-material with zensical, since mkdocs v1 is no longer
maintained. Zensical reads mkdocs.yml natively, so no config format
conversion is needed.

- Replace mkdocs-material, mkdocs-minify-plugin, mkdocs-redirects with
  zensical in requirements.txt
- Remove unsupported plugin configs (minify, redirects) and hooks from
  mkdocs.yml; add site_dir: rendered
- Add website/post-build.sh to generate redirect HTML pages and the
  Plausible analytics proxy endpoint, replacing the mkdocs-redirects
  plugin and hooks.py respectively
- Delete hooks.py (superseded by post-build.sh)
- Update CI workflow to use zensical build and run the post-build script

Author: mandre

.github/workflows/website.yaml

@@ -25,7 +25,10 @@ jobs:
       run: pip install -Ur website/requirements.txt
 
     - name: Build the site
-      run: mkdocs build --verbose --strict --config-file website/mkdocs.yml --site-dir rendered
+      run: zensical build --strict --config-file website/mkdocs.yml
+
+    - name: Post-build (redirects and analytics)
+      run: bash website/post-build.sh website/rendered
 
     - name: Publish to Cloudflare Pages
       uses: cloudflare/pages-action@f0a1cd58cd66095dee69bfa18fa5efd1dde93bca # tag=v1.5.0

website/hooks.py

@@ -47,8 +47,7 @@ extra:
       link: https://github.com/k-orc/openstack-resource-controller
     - icon: fontawesome/brands/slack
       link: slack://channel?team=T09NY5SBT&id=C05G4NJ6P6X
-hooks:
-  - hooks.py
+site_dir: rendered
 theme:
   name: material
   custom_dir: overrides
@@ -63,25 +62,26 @@ theme:
     - search.highlight
     - search.suggest
     - toc.integrate
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: lucide/sun-moon
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: lucide/sun
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: lucide/moon
+        name: Switch to system preference
 plugins:
   - search:
-  - minify:
-      minify_html: true
-      minify_js: true
-      minify_css: true
-      htmlmin_opts:
-        remove_comments: true
-      cache_safe: true
-  - redirects:
-      redirect_maps:
-        'getting_started.md': 'getting-started.md'
-        'development/index.md': 'development/contributing.md'
-        'development/controller-design.md': 'development/controller-implementation.md'
-        'development/design-decisions.md': 'concepts/design-principles.md'
-        'development/coding-convention.md': 'development/coding-standards.md'
-        'development/api-contracts.md': 'development/api-design.md'
-        'user-guide/index.md': 'concepts/core-concepts.md'
-        'user-guide/drift-detection.md': 'concepts/drift-detection.md'
 markdown_extensions:
   - admonition
   - attr_list

website/mkdocs.yml

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Post-build script for zensical/mkdocs site.
+# Generates redirect pages and analytics proxy endpoint.
+
+set -euo pipefail
+
+SITE_DIR="${1:?Usage: $0 <site-dir>}"
+
+# --- Redirects ---
+# Replaces mkdocs-redirects plugin. Each entry maps an old path (directory URL)
+# to a new relative URL.
+declare -A REDIRECTS=(
+  ["getting_started"]="../getting-started/"
+  ["development/controller-design"]="../controller-implementation/"
+  ["development/design-decisions"]="../../concepts/design-principles/"
+  ["development/coding-convention"]="../coding-standards/"
+  ["development/api-contracts"]="../api-design/"
+  ["user-guide/drift-detection"]="../../concepts/drift-detection/"
+)
+
+# index.md redirects are special: they build to <dir>/index.html directly
+declare -A INDEX_REDIRECTS=(
+  ["development"]="contributing/"
+  ["user-guide"]="../concepts/core-concepts/"
+)
+
+for src in "${!REDIRECTS[@]}"; do
+  dest="${REDIRECTS[$src]}"
+  dir="$SITE_DIR/$src"
+  mkdir -p "$dir"
+  cat > "$dir/index.html" <<EOF
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="refresh" content="0; url=$dest">
+  <link rel="canonical" href="$dest">
+</head>
+<body>
+  <p>This page has moved. If you are not redirected, <a href="$dest">click here</a>.</p>
+</body>
+</html>
+EOF
+done
+
+for src in "${!INDEX_REDIRECTS[@]}"; do
+  dest="${INDEX_REDIRECTS[$src]}"
+  dir="$SITE_DIR/$src"
+  mkdir -p "$dir"
+  cat > "$dir/index.html" <<EOF
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="refresh" content="0; url=$dest">
+  <link rel="canonical" href="$dest">
+</head>
+<body>
+  <p>This page has moved. If you are not redirected, <a href="$dest">click here</a>.</p>
+</body>
+</html>
+EOF
+done
+
+# --- Analytics proxy endpoint ---
+# Replaces hooks.py on_post_build. Creates an empty script for the Plausible
+# analytics reverse-proxy setup.
+mkdir -p "$SITE_DIR/t/p"
+touch "$SITE_DIR/t/p/script.js"

website/post-build.sh

@@ -1,3 +1 @@
-mkdocs-material
-mkdocs-minify-plugin
-mkdocs-redirects
+zensical