docs: add VitePress site deployed to GitHub Pages on release#101
Merged
Conversation
Replace the dated GitHub-managed Jekyll build (docs/_config.yml, just-the-docs) with a VitePress site that reads the existing docs/*.md in place. The palette and fonts mirror the application (src/client/ globals.css) so the docs and product read as one surface. Highlights: - Custom fullscreen zoom/pan viewer for mermaid diagrams (no new dep). - Built-in local search (MiniSearch); no external service. - New copy-paste Quick start whose first test needs zero agent code. - All prose rewritten for a junior-dev audience; no em dashes. - Deploys on a v*.*.* tag (mirrors publish.yml) + PR build-only check. - Local preview: a docs service in compose.dev.yaml + pnpm docs:* scripts. Supply chain (each documented + dated in pnpm-workspace.yaml): - trustPolicyExclude: [vite] for the npm trusted-publisher -> provenance attestation transition (benign, dev-only, never in the prod image). - VEX ignoreGhsas for 5 dev-only docs-toolchain advisories (3 vite + 1 esbuild dev-server, 1 dompurify); the deployed site is static HTML. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Dependency ReviewThe following issues were found:
|
The Supply-chain audit job failed on dependency-review-action: vite@5.4.21 (pulled in by vitepress) trips three advisories — GHSA-fx2h-pf6j-xcff, GHSA-4w7w-66w2-5vf9, GHSA-v6wh-96g9-6wx3. These are already dispositioned "NOT AFFECTED" in pnpm-workspace.yaml's auditConfig.ignoreGhsas, but dependency-review-action keeps its own allowlist and does not read pnpm's config, so the same dispositions are mirrored into `allow-ghsas`. All five docs-toolchain advisories are dev-only (dropped by the prod image's --prod install) with a static-HTML deploy, so none has a production surface. The dual-licensed dompurify (MPL-2.0 OR Apache-2.0) and the "unknown" khroma license show in the action's summary but do not fail the build — the OR is satisfied by permissive Apache-2.0 and unknown licenses warn rather than block — so no license override is needed. Also: - docs.yml: concurrency cancel-in-progress=false so a tag push can't cancel an in-flight Pages deploy (mirrors publish.yml). - Layout.vue: append the zoom overlay only after the element guard passes, and drop a gratuitous double cast on the already-typed <svg> element. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
With the docs-toolchain vulnerabilities now allow-listed, dependency-review surfaces its next gate: dompurify trips the copyleft deny-list on its `MPL-2.0 OR Apache-2.0` dual license. The OR lets us take it under permissive Apache-2.0 (no copyleft obligation), and it is a dev-only dep (mermaid → dompurify) that the prod image's --prod install drops and never inlines into the shipped SPA bundle, so the bundle source-availability concern the deny-list guards cannot arise. Carve it out by purl (version-agnostic). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The deploy job lived in docs.yml alongside the pull_request-triggered build gate, so every docs PR showed a "Deploy to GitHub Pages" check sitting at "Skipped" — a job inside a PR-triggered workflow always renders, the job-level if only stops it running. Split by trigger instead of hiding behind an if: - docs.yml — deploy only (build + deploy), tags + workflow_dispatch. Never PR-triggered, so neither job appears on PRs. - docs-check.yml — PR build-gate, compile-only, no Pages permissions. Keeping deploy as its own job/workflow (rather than folding it into the build job) preserves least-privilege: pages:write / id-token:write never get granted on PR runs, including fork PRs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the dated GitHub-managed Jekyll site (
docs/_config.yml,just-the-docs) with a modern VitePress site. It reads the existingdocs/*.mdin place (no content move), so the README links and the/audit-docssource-to-doc map stay valid. The palette and fonts mirror the app itself (src/client/globals.css), so docs and product read as one surface.The docs site builds in CI and deploys to GitHub Pages on a release tag. Until now there was no docs CI; the old site was published by GitHub's managed Jekyll on every push to
main.What changed
docs/.vitepress/(config + custom theme + a custom Layout). Built-in local search (MiniSearch, no external service).docs/quickstart.md): copy-paste, and the first test needs zero agent code changes (xray records the agent from the room;attach+XRAY_OTLP_ENDPOINTare now an optional "go further" step, only for tool/model assertions)..github/workflows/docs.yml(two jobs, official Pages flow, all actions SHA-pinned). Deploys onv*.*.*tags, PRs get a build-only check, plus aworkflow_dispatchescape hatch.docsservice incompose.dev.yamlserves a live-reload preview onDOCS_PORT(5173), plusdocs:dev/docs:build/docs:previewscripts._config.ymland an unused, stalehero.png.Supply chain
VitePress is a dev dependency only (dropped by the prod image's
--prodinstall). Two policy additions, each documented and dated inpnpm-workspace.yaml:trustPolicyExclude: [vite]— vite trippedno-downgradebecause current 5.4.x carry Sigstore provenance while older releases carried npm trusted-publisher evidence. Benign ecosystem shift, verified across 5.4.0..5.4.21.auditConfig.ignoreGhsasfor 5 advisories in the dev-only docs toolchain (3 vite + 1 esbuild dev-server, 1 dompurify). All are dev-server or non-prod classes; the deployed site is static HTML. The vite findings have no 5.x backport. The dompurify fix is still inside the 7-day cooldown; there's a note to convert it to anoverridespin once it clears (~2026-06-24).How to verify
/xray/quickstartand/xray/architecture. Click a mermaid diagram: it opens fullscreen with zoom/pan.pnpm devbrings the app up on :8080 and the docs on :5173 with hot reload.Verified locally:
pnpm docs:build(clean, no dead links),pnpm audit --audit-level=moderate(exit 0),pnpm typecheck,pnpm check(biome) all pass.One-time setup before the first deploy
In repo Settings -> Pages -> Source, switch to "GitHub Actions" (replacing "Deploy from a branch /docs"). After that, the site publishes on the next
v*.*.*tag (or a manualworkflow_dispatch) at https://xray-eval.github.io/xray/.🤖 Generated with Claude Code