MkDocs to Zensical migration; use uv

.github/workflows/mkdocs-build.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - name: Setup Python environment
-        run: pip install -r requirements.txt
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
       - name: Build docs with --strict
         run: make build-docs

.github/workflows/update-livesite.yml

@@ -15,5 +15,6 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: pip install -r requirements.txt
-      - run: mkdocs gh-deploy --force --strict
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - run: uv run zensical gh-deploy --force --strict

.gitignore

@@ -3,7 +3,4 @@ env/
 venv/
 .idea/
 .DS_Store
-.python-version
 inbound-links.md
-pyproject.toml
-uv.lock

Makefile

@@ -2,27 +2,19 @@
 
 .PHONY: install-dev
 install-dev:
-	python -m pip install --upgrade wheel pip
-	pip install -r requirements.txt
+	uv sync
 
 
 .PHONY: generate-inbound-links
 generate-inbound-links:
-	python3 scripts/generate_inbound_links.py
+	uv run python scripts/generate_inbound_links.py
 
-# URL validation approach #1
-# .PHONY: build-docs
-# build-docs: generate-inbound-links
-# 	mkdocs build --strict
-# 	rm -rfd site/inbound-links
-
-# URL validation approach #2
 .PHONY: build-docs
 build-docs:
 	@echo "Building site..."
-	mkdocs build --strict
+	uv run zensical build --strict
 	@echo "Validating inbound links..."
-	python3 scripts/validate_inbound_links.py
+	uv run python scripts/validate_inbound_links.py
 
 .PHONY: clean
 clean:
@@ -34,10 +26,9 @@ clean:
 .PHONY: all
 all: build-docs
 
-# URL validation approach #1
 .PHONY: serve
 serve: generate-inbound-links
 	@echo "Finding available port..."
-	$(eval PORT := $(shell python scripts/find_port.py))
-	@echo "Starting MkDocs server on port $(PORT)..."
-	mkdocs serve -a 127.0.0.1:$(PORT)
+	$(eval PORT := $(shell uv run python scripts/find_port.py))
+	@echo "Starting Zensical server on port $(PORT)..."
+	uv run zensical serve -a 127.0.0.1:$(PORT)

README.md

@@ -3,17 +3,9 @@ Source for the documentation located at https://docs.alcf.anl.gov/
 
 ## Contributing to documentation
 
-### Python environment
+### Prerequisites
 
-To build documentation locally, you need a Python environment with `mkdocs` installed.  Check that Python 3.6+ is installed:
-```bash
-python --version
-```
-e.g. `Python 3.8.3`. Then create a new virtual env to isolate the `mkdocs` installation:
-```bash
-python -m venv env
-source env/bin/activate
-```
+To build documentation locally, you need [uv](https://docs.astral.sh/uv/getting-started/installation/) installed. It manages Python, virtual environments, and dependencies automatically.
 
 ### Git
 
@@ -24,22 +16,22 @@ cd user-guides
 git submodule init; git submodule update
 ```
 
-### Installing MkDocs
+### Installing dependencies
 
-To install `mkdocs` in the current environment: 
+`uv sync` reads `pyproject.toml` and installs Zensical and all plugins into a managed virtualenv:
 ```bash
 cd user-guides
 make install-dev
 ```
 
 ### Preview the docs locally and test for errors
 
-Run `mkdocs serve` or `make serve` to auto-build and serve the docs for preview in your web browser:
+Run `zensical serve` or `make serve` to auto-build and serve the docs for preview in your web browser:
 ```bash
 make serve
 ```
 
-GitHub Actions are used to automatically validate all changes in pull requests before they are merged, by executing `mkdocs build --strict`. The [`--strict`](https://www.mkdocs.org/user-guide/configuration/#validation) flag will print out warnings and return a nonzero code if any of a number of checks fail (e.g. broken relative links, orphaned Markdown pages that are missing from the navigation sidebar, etc.). To see if your changes will pass these tests, run the following command locally:
+GitHub Actions are used to automatically validate all changes in pull requests before they are merged, by executing `zensical build --strict`. The `--strict` flag will print out warnings and return a nonzero code if any of a number of checks fail (e.g. broken relative links, orphaned Markdown pages that are missing from the navigation sidebar, etc.). To see if your changes will pass these tests, run the following command locally:
 ```
 make build-docs
 ```
@@ -76,5 +68,5 @@ git push origin YOURBRANCH         # push the changes from local branch up to yo
 External URLs pointing to our docs are tracked in [includes/validate-inbound-URLs.txt](includes/validate-inbound-URLs.txt) and validated during build to prevent broken links from the main ALCF site, etc. Add URLs to that file to ensure that the matching `.md` in this repository is never moved, renamed, or deleted.
 
 There are two Python `scripts/` that perform this function:
-1. (works with `mkdocs build` and `serve`): Translate URLs to relative path links to their matching source `.md` files; write these links to `docs/inbound-links.md`. Use MkDocs' built-in validation (adding `--strict` flag when running `mkdocs build`, in order to return an error code if they are invalid).
-2. (works with `mkdocs build`, only): Use a lightweight post-build validation on generated `site/` directory HTML contents.
+1. (works with `zensical build` and `serve`): Translate URLs to relative path links to their matching source `.md` files; write these links to `docs/inbound-links.md`. Use Zensical's built-in validation (adding `--strict` flag when running `zensical build`, in order to return an error code if they are invalid).
+2. (works with `zensical build`, only): Use a lightweight post-build validation on generated `site/` directory HTML contents.