Migrate from mkdocs to zensical

Author: jonathan343

.gitignore

@@ -1,9 +1,8 @@
 # macOS system files
 .DS_Store
 
-# MkDocs build artifacts
+# Docs build artifacts
 site/
-docs/SUMMARY.md
 docs/clients/
 **/docs/client/
 

Makefile

@@ -1,24 +1,27 @@
 DOCS_PORT ?= 8000
 PYTHON_VERSION := 3.12
 
-.PHONY: docs docs-serve docs-clean docs-install venv
+.PHONY: docs docs-serve docs-clean docs-install docs-lock venv
 
 venv:
 	uv venv --python $(PYTHON_VERSION)
 
+docs-lock: venv
+	uv pip compile requirements-docs.in -o requirements-docs.txt
+
 docs-install: venv
-	uv pip install -r requirements-docs.in
+	uv pip install -r requirements-docs.txt
 	uv pip install -e clients/*
 
 docs-clean:
-	rm -rf site docs/clients docs/SUMMARY.md
+	rm -rf site docs/clients
 
 docs-generate:
 	uv run python scripts/docs/generate_all_doc_stubs.py
 	uv run python scripts/docs/generate_nav.py
 
 docs: docs-generate
-	uv run mkdocs build
+	uv run zensical build
 
 docs-serve:
 	@[ -d site ] || $(MAKE) docs

docs/hooks/copyright.py

@@ -1,29 +1,59 @@
 /**
- * Keep API Reference nav expanded on /clients/ pages and highlight active client.
- * Uses Material for MkDocs document$ observable for instant navigation compatibility.
+ * Keep the active client highlighted and its nav section expanded across all
+ * of its API reference pages (/clients/<name>/...).
+ *
+ * Zensical already auto-expands "Available Clients" and highlights the active
+ * client on that client's own index page, but not on its nested symbol pages
+ * (operations/, enums/, structures/, unions/, errors/). This restores that
+ * orientation so the sidebar stays anchored while browsing a client's API.
  */
-function expandClientsNav() {
-  if (!location.pathname.includes("/clients/")) return;
-  document.querySelectorAll(".md-nav__item--nested").forEach(function (item) {
-    var link = item.querySelector(":scope > .md-nav__link");
-    if (link && link.textContent.trim().includes("Available Clients")) {
-      // Expand "All Available Clients" drop down
-      var toggle = item.querySelector(":scope > .md-nav__toggle");
-      if (toggle) toggle.checked = true;
-      item.setAttribute("data-md-state", "expanded");
-      
-      // Highlight active client
-      var navItems = item.querySelectorAll(".md-nav__item .md-nav__link");
-      navItems.forEach(function (navLink) {
-        if (navLink.href && location.pathname.includes(navLink.pathname)) {
-          navLink.classList.add("md-nav__link--active");
-        }
-      });
+function highlightActiveClient() {
+  // Match ".../clients/<name>/..." and capture the client segment.
+  var match = location.pathname.match(/\/clients\/([^/]+)\//);
+  if (!match) return;
+
+  // Reconstruct the client's index path, e.g. "/clients/polly/", preserving
+  // any site base path (the docs are served under a sub-path in production).
+  var clientRoot =
+    location.pathname.slice(0, match.index) + "/clients/" + match[1] + "/";
+
+  // Scope to the primary sidebar only. The secondary "On this page" TOC uses
+  // the same link classes, and its same-page anchors would otherwise all match
+  // clientRoot on a client's index page and get highlighted.
+  var sidebar = document.querySelector(".md-nav--primary");
+  if (!sidebar) return;
+
+  // The client appears exactly once in the sidebar, so find it and stop —
+  // avoids scanning the rest of the nav (hundreds of links once many clients
+  // exist).
+  var links = sidebar.querySelectorAll(".md-nav__link[href]");
+  var link = null;
+  for (var i = 0; i < links.length; i++) {
+    if (links[i].pathname === clientRoot && !links[i].hash) {
+      link = links[i];
+      break;
     }
-  });
+  }
+  if (!link) return;
+
+  // Highlight the client whose pages we're currently viewing.
+  link.classList.add("md-nav__link--active");
+
+  // Expand every collapsible ancestor (incl. "Available Clients") so the
+  // highlighted link is visible. Expansion is driven by the toggle checkbox.
+  var item = link.closest(".md-nav__item--nested");
+  while (item) {
+    var toggle = item.querySelector(":scope > .md-nav__toggle");
+    if (toggle) toggle.checked = true;
+    var parent = item.parentElement;
+    item = parent && parent.closest(".md-nav__item--nested");
+  }
 }
 
-// Subscribe to Material's document$ observable for instant navigation support
-document$.subscribe(expandClientsNav);
-// Also run on initial page load
-expandClientsNav();
+// Re-run on every instant-navigation page load; fall back to a one-time run if
+// the document$ observable isn't available.
+if (typeof document$ !== "undefined" && document$.subscribe) {
+  document$.subscribe(highlightActiveClient);
+} else {
+  highlightActiveClient();
+}

docs/javascript/nav-expand.js

@@ -1,4 +1,2 @@
-mkdocs==1.6.1
-mkdocstrings[python]==1.0.0
-mkdocs-material==9.7.0
-mkdocs-literate-nav==0.6.1
+mkdocstrings[python]~=1.0.4
+zensical~=0.0.46

mkdocs.yml

@@ -0,0 +1,81 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile requirements-docs.in -o requirements-docs.txt
+click==8.4.2
+    # via
+    #   mkdocs
+    #   zensical
+deepmerge==2.1.0
+    # via zensical
+ghp-import==2.1.0
+    # via mkdocs
+griffelib==2.1.0
+    # via mkdocstrings-python
+jinja2==3.1.6
+    # via
+    #   mkdocs
+    #   mkdocstrings
+    #   zensical
+markdown==3.10.2
+    # via
+    #   mkdocs
+    #   mkdocs-autorefs
+    #   mkdocstrings
+    #   pymdown-extensions
+    #   zensical
+markupsafe==3.0.3
+    # via
+    #   jinja2
+    #   mkdocs
+    #   mkdocs-autorefs
+    #   mkdocstrings
+mergedeep==1.3.4
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+mkdocs==1.6.1
+    # via
+    #   mkdocs-autorefs
+    #   mkdocstrings
+mkdocs-autorefs==1.4.4
+    # via
+    #   mkdocstrings
+    #   mkdocstrings-python
+mkdocs-get-deps==0.2.2
+    # via mkdocs
+mkdocstrings==1.0.4
+    # via
+    #   -r requirements-docs.in
+    #   mkdocstrings-python
+mkdocstrings-python==2.0.5
+    # via mkdocstrings
+packaging==26.2
+    # via mkdocs
+pathspec==1.1.1
+    # via mkdocs
+platformdirs==4.10.0
+    # via mkdocs-get-deps
+pygments==2.20.0
+    # via zensical
+pymdown-extensions==11.0
+    # via
+    #   mkdocstrings
+    #   zensical
+python-dateutil==2.9.0.post0
+    # via ghp-import
+pyyaml==6.0.3
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+    #   pymdown-extensions
+    #   pyyaml-env-tag
+    #   zensical
+pyyaml-env-tag==1.1
+    # via mkdocs
+six==1.17.0
+    # via python-dateutil
+tomli==2.4.1
+    # via zensical
+watchdog==6.0.0
+    # via mkdocs
+zensical==0.0.46
+    # via -r requirements-docs.in