CNTRLPLANE-3945: Migrate documentation tooling from mkdocs-material to zensical

.github/workflows/docs-build-reusable.yaml

@@ -15,15 +15,9 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
-        with:
-          python-version: '3.x'
-      - name: Install documentation dependencies
-        run: pip install --require-hashes -r docs/requirements.txt
-        env:
-          PIP_CACHE_DIR: ${{ runner.temp }}/.pip-cache
+      - uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6.1.0
       - name: Build documentation
-        run: mkdocs build --strict
+        run: uv run --frozen zensical build --strict
         working-directory: docs
       - name: Save PR metadata
         run: echo "${{ github.event.pull_request.number }}" > docs/site/pr-number.txt

docs/Makefile

@@ -1,31 +1,21 @@
 RUNTIME ?= $(shell sh ../hack/utils.sh get_container_engine)
-version := $(shell awk -f image-version.awk requirements.txt)
-VERSION ?= $(if $(MKDOCS_TAG),$(MKDOCS_TAG),$(version))
-IMG ?= quay.io/hypershift/mkdocs-material:$(VERSION)
+IMG ?= docker.io/zensical/zensical:0.0.51
 
 .PHONY: build
 build:
-	mkdocs build
+	uv run --frozen zensical build --strict
 
 .PHONY: build-containerized
 build-containerized:
 	$(RUNTIME) volume create --ignore hypershift-docs-site
 	$(RUNTIME) run --rm -it \
-		-v ${PWD}:/home/docs/hypershift:Z \
-		-v hypershift-docs-site:/home/docs/hypershift/site \
+		-v ${PWD}:/docs:Z \
+		-v hypershift-docs-site:/docs/site \
 		$(IMG) build --strict
 
 .PHONY: serve-containerized
 serve-containerized:
 	$(RUNTIME) run --rm -it -p 8000:8000 \
-		-v ${PWD}:/home/docs/hypershift:Z \
-		-v hypershift-docs-site:/home/docs/hypershift/site \
-		$(IMG) serve --dev-addr 0.0.0.0:8000
-
-.PHONY: image
-image:
-	$(RUNTIME) build -t $(IMG) .
-
-.PHONY: push
-push:
-        $(RUNTIME) push $(IMG)
+		-v ${PWD}:/docs:Z \
+		-v hypershift-docs-site:/docs/site \
+		$(IMG)

docs/README.md

@@ -2,49 +2,39 @@ Any changes to the docs in this directory can be tested locally before pushing c
 steps:
 
 1. cd to this directory
-2. Run `make image` to build the image
-3. Run `make build-containerized` to build the containerized version of the image
-4. Run `make serve-containerized` to serve up the docs website locally
+2. Run `make build-containerized` to build the containerized version of the image
+3. Run `make serve-containerized` to serve up the docs website locally
 
 Any changes you make while the docs are served locally, will be updated in the local docs website.
 
-## Managing Python dependencies
+## Configuration
+
+The site configuration lives in `mkdocs.yml`. Zensical still uses the MkDocs
+configuration format; once Zensical ships a migration tool for its native TOML
+config, we will switch over.
 
-`requirements.txt` pins every Python dependency needed to build the docs
-(mkdocs and its plugins) to an exact version and includes
-`--hash=sha256:...` entries for each published artifact, enabling pip's
-hash-checking mode (`pip install --require-hashes`). This is what
-`.github/workflows/docs-build-reusable.yaml` installs before running
-`mkdocs build --strict`.
+## Managing Python dependencies
 
-Because hash-checking mode requires every installed package — including
-transitive dependencies of mkdocs-material, mkdocs-mermaid2-plugin, and
-mkdocs-glightbox — to be pinned and hashed, the file lists the full resolved
-dependency closure, not just the three plugins imported directly.
+Dependencies are declared in `pyproject.toml` and locked with
+[`uv`](https://docs.astral.sh/uv/) into `uv.lock`, which pins every
+direct and transitive package to an exact version with hash verification
+for supply chain security. This is what
+`.github/workflows/docs-build-reusable.yaml` uses when running
+`uv run --frozen zensical build --strict`.
 
 ### Adding or updating a dependency
 
-1. Add or update the package's version constraint in `requirements.txt`
-   (e.g. `newplugin>=1.0.0`, or bump an existing `==` pin).
-2. Regenerate the file with [`uv`](https://docs.astral.sh/uv/), compiling to
-   a new temporary path rather than overwriting `requirements.txt` directly,
-   then move it into place:
+1. Add or update the package in `pyproject.toml`
+   (e.g. add `"newplugin>=1.0.0"` to `dependencies`, or bump an existing pin).
+2. Regenerate the lockfile:
 
    ```bash
-   uv pip compile --generate-hashes docs/requirements.txt -o /tmp/requirements.txt.new
-   mv /tmp/requirements.txt.new docs/requirements.txt
+   uv lock
    ```
 
-   This resolves the full dependency graph, pins every package (direct and
-   transitive) to an exact version, and adds `--hash=sha256:...` entries for
-   all of its published wheel/sdist artifacts. Don't edit hashes by hand —
-   always regenerate so they're guaranteed to match the published artifact.
-3. Validate the result, forcing pip to actually verify every package's hash
-   rather than skipping ones already present locally:
+3. Confirm the docs still build:
 
    ```bash
-   pip install --dry-run --ignore-installed --require-hashes -r docs/requirements.txt
+   uv run --frozen zensical build --strict
    ```
 
-4. Confirm the docs still build: `cd docs && mkdocs build --strict`
-   (after installing the regenerated requirements into your environment).

docs/content/contribute/contribute-docs.md

@@ -4,10 +4,9 @@ title: Contribute documentation
 
 # Contributing documentation
 
-HyperShift's documentation is based on [MkDocs](https://www.mkdocs.org) with the
-[Material theme](https://squidfunk.github.io) and roughly follows the
-[Diátaxis Framework](https://diataxis.fr) for content organization and stylistic
-approach.
+HyperShift's documentation is based on [Zensical](https://zensical.org) and
+roughly follows the [Diátaxis Framework](https://diataxis.fr) for content
+organization and stylistic approach.
 
 The documentation site is built and published automatically to [https://hypershift.pages.dev/](https://hypershift.pages.dev/).
 
@@ -17,12 +16,8 @@ All documentation lives in the [`docs` directory](https://github.com/openshift/h
 
 All content should be Markdown files placed in the [`docs/content` directory](https://github.com/openshift/hypershift/tree/main/docs/content).
 The [MkDocs configuration file](https://github.com/openshift/hypershift/blob/main/docs/mkdocs.yml)
-contains all the MkDocs and Material theme configuration, including the navigation
-structure for the site.
-
-The `quay.io/hypershift/mkdocs-material:latest` image ([Dockerfile](https://github.com/openshift/hypershift/blob/main/docs/Dockerfile))
-is published to provide an easy and portable way to run `mkdocs` fully configured
-to preview the site equivalent to the published site.
+contains all the Zensical configuration, including the navigation structure for
+the site.
 
 !!! note
 
@@ -53,20 +48,19 @@ To start a live preview of the site which automatically rebuilds and refreshes i
 response to local content and configuration changes, run the following from the
 `docs` directory:
 
-```shell
-make serve-containerized
-```
+=== "Native"
 
-Visit the site at [http://0.0.0.0:8000](http://0.0.0.0:8000).
+    ```shell
+    uv run --frozen zensical serve
+    ```
 
-!!! note
+=== "Containerized"
 
-    The `serve-containerized` Make target runs the `quay.io/hypershift/mkdocs-material:latest`
-    image with the local container runtime. Running `mkdocs` natively is possible
-    but not supported.
+    ```shell
+    make serve-containerized
+    ```
 
-    If you need more control over the local preview server, consult [the Makefile](https://github.com/openshift/hypershift/blob/main/docs/Makefile)
-    as a guide to constructing your own local server command.
+Visit the site at [http://127.0.0.1:8000](http://127.0.0.1:8000).
 
 ## Generate the API reference
 

docs/content/how-to/ci/docs-preview.md

@@ -6,7 +6,7 @@ When a pull request modifies files under `docs/`, GitHub Actions workflows autom
 
 The preview system uses two separate workflows for security, following the reusable workflow pattern described in [GitHub Actions Workflows](github-actions.md):
 
-1. **Docs Build** (`.github/workflows/docs-build.yaml`) — triggers on `pull_request` for changes under `docs/`. The caller delegates to `docs-build-reusable.yaml@main`, which checks out the PR code, builds with MkDocs in strict mode, and uploads the built site as an artifact. This workflow has no access to secrets.
+1. **Docs Build** (`.github/workflows/docs-build.yaml`) — triggers on `pull_request` for changes under `docs/`. The caller delegates to `docs-build-reusable.yaml@main`, which checks out the PR code, builds with Zensical in strict mode, and uploads the built site as an artifact. This workflow has no access to secrets.
 2. **Docs Deploy** (`.github/workflows/docs-deploy.yaml`) — triggers via `workflow_run` when the Docs Build workflow completes successfully. It downloads the built artifact and deploys to Cloudflare Pages. This workflow has access to the `docs-preview` environment secrets but never executes PR code.
 
 GitHub shows a **View deployment** link in the PR timeline via the `docs-preview` environment.
@@ -30,8 +30,7 @@ To preview documentation locally:
 
 ```bash
 cd docs
-pip install -r requirements.txt
-mkdocs serve
+uv run zensical serve
 ```
 
 Then open [http://127.0.0.1:8000](http://127.0.0.1:8000).

docs/content/how-to/ci/github-actions.md

@@ -52,7 +52,7 @@ All workflows run on self-hosted ARC runners and target the `main` and `release-
 
 | Caller | Reusable | Purpose |
 |--------|----------|---------|
-| `docs-build.yaml` | `docs-build-reusable.yaml` | Build MkDocs site in strict mode |
+| `docs-build.yaml` | `docs-build-reusable.yaml` | Build Zensical site in strict mode |
 
 !!! info
     The `docs-deploy.yaml` workflow is not a reusable workflow pair — it triggers via `workflow_run` after the Docs Build completes to deploy the preview. See [Documentation Preview](docs-preview.md) for details.

docs/content/how-to/ci/triage/presubmit-failures.md

@@ -105,7 +105,7 @@ These checks only run when relevant files change:
 |------------|-------------|-----------------|
 | **Envtest OCP API Validation** | `api/`, `test/envtest/`, CRD test assets | `FAIL` with the test name — see `test/envtest/README.md` for details |
 | **Envtest Vanilla Kube API Validation** | Same as above | Same as above |
-| **Docs Build** | `docs/**` changes | MkDocs build errors — usually a broken link or YAML syntax error |
+| **Docs Build** | `docs/**` changes | Zensical build errors — usually a broken link or YAML syntax error |
 | **Validate CPO Overrides** | `hypershift-operator/controlplaneoperator-overrides/assets/overrides.yaml` changes | Validation error for the CPO overrides file |
 | **gocacheprog Tests** | `contrib/ci/gocacheprog/**` changes | `FAIL` with the test name |
 

docs/mkdocs.yml

@@ -7,11 +7,6 @@ theme:
   - content.code.annotate
 plugins:
 - search
-- mermaid2:
-    version: 11.2.0
-    javascript: https://unpkg.com/mermaid@11.2.0/dist/mermaid.min.js
-    arguments:
-      securityLevel: loose
 - glightbox:
     touchNavigation: true
     loop: false
@@ -43,7 +38,7 @@ markdown_extensions:
     custom_fences:
     - name: mermaid
       class: mermaid
-      format: !!python/name:mermaid2.fence_mermaid
+      format: !!python/name:pymdownx.superfences.fence_code_format
 - pymdownx.snippets
 - admonition
 - pymdownx.details

docs/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "hypershift-docs"
+version = "0.1.0"
+description = "HyperShift documentation"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["zensical==0.0.51"]