Docs site

The published site at mocks.calab.ai is a static export of the Markdown under docs/. Generation uses the same docs-site skill as calab-ai/neuralops-accelerator (the engine behind docs.neuralop.ai).

Local preview

Requires Node.js 18+.

cd .agents/skills/docs-site
npm ci
npm run vendor
node server.js --root docs --no-open

Then open http://127.0.0.1:4173/. The server watches docs/ and reloads on edit. Entra gating uses docs-site.config.json auth (handbook SPA IDs) unless you override with ENTRA_CLIENT_ID / ENTRA_TENANT_ID. Localhost redirects must be on that app before sign-in works in preview.

Static export

cd .agents/skills/docs-site
npm ci
npm run vendor
npm run export

Output lands in dist/ (see docs-site.config.json). The export writes:

  • one HTML page per Markdown file (index.md becomes dist/index.html)
  • search-index.json and graph.json
  • Release notes stay off (releases.enabled is false). This repo uses Linear Releases, not GitHub Releases, so the GitHub-backed /releases page would be empty.
  • CNAME (mocks.calab.ai) and .nojekyll for GitHub Pages
  • Entra overlay scripts when valid GUIDs are present in env or docs-site.config.json auth

GitHub Pages

.github/workflows/docs-site-pages.yml builds and deploys on push to main and on workflow_dispatch. Export writes CNAME mocks.calab.ai into the Pages artifact. Auth IDs come from repository secrets when set, otherwise from docs-site.config.json auth (handbook SPA).

After the first successful deploy on main:

  1. Repo Settings → Pages → Build and deployment → Source: GitHub Actions.
  2. Custom domain: mocks.calab.ai.
  3. Azure DNS (zone calab.ai, RG calabs-all-shared): CNAME name mocks → calab-ai.github.io (TTL 3600, same as handbook.calab.ai).
  4. Merge SPA redirects on calab-handbook-auth (see entra-auth.md). Optional: repository secrets ENTRA_CLIENT_ID / ENTRA_TENANT_ID to override the config-file IDs.
  5. Once Entra sign-in is confirmed on the live site, set Pages visibility to public. Auth is built into the app; GitHub's private-Pages gate is no longer required. Do not flip public before the overlay is in the deployed artifact.

Configuration

Repo-root docs-site.config.json controls title, scan root, release notes, and the Pages hostname. It is loaded first and wins. A skill-directory docs-site.config.json is only a legacy fallback when the repo-root file is absent. Do not add one under .agents/skills/docs-site/.

What is published

Everything under docs/ except paths listed in exclude. Agent-facing notes under docs/agents/ are included; they are internal process docs, not Azure secrets.