Deploying docs¶

The public docs site is a static Zensical build. Vercel does not need native Zensical framework support. Configure the Vercel project with docs/ as its root directory, install the Python docs toolchain with uv, run the Zensical build wrapper, and publish the generated site/ directory.

Vercel project¶

Create a Vercel project from the Git repository with these settings:

Vercel should install with uv sync --frozen --no-dev. Vercel should build with uv run --frozen bash ./vercel-build.sh. Vercel should publish the generated site/ directory.

Repository config¶

Prefer committing the deployment settings instead of relying only on dashboard state. docs/vercel.json keeps Vercel builds reproducible from main:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": null,
  "installCommand": "uv sync --frozen --no-dev",
  "buildCommand": "uv run --frozen bash ./vercel-build.sh",
  "outputDirectory": "site"
}

The docs directory also carries its own uv project metadata in docs/pyproject.toml and docs/uv.lock. The Zensical project config lives in docs/zensical.toml so the docs deployment files stay together:

[project]
name = "kata-docs"
version = "0.0.0"
requires-python = ">=3.12"
dependencies = [
  "zensical==0.0.43",
]

[tool.uv]
package = false

Keep the Zensical version aligned with requirements-docs.txt until the repository fully moves docs dependency management to uv.

Verification¶

Before changing the Vercel project or merging deployment config, verify the same build path locally:

cd docs
uv sync --frozen --no-dev
uv run --frozen bash ./vercel-build.sh

The build should finish with generated static files under docs/site/. The normal repository docs check remains:

make docs-check

Useful Vercel references:

• Project configuration with vercel.json
• Build customization
• Python dependency formats and uv support