[adrienlacombe]

Deploys the docs to https://starknet-io.github.io/get-starknet with GitHub Pages, replacing Vercel (get-starknet.starknet-react.com).

Stacked on #347 (vocs 2), which produces the static build this deploys. The base is #347's branch, so the diff shows only this change. GitHub retargets it to master when #347 merges.

Before merging: a repo admin enables Pages

Settings → Pages → Source: GitHub Actions. Until then the deploy job fails, but the build still runs. The workflow can't enable Pages itself, because GITHUB_TOKEN doesn't have admin rights.

Changes

• .github/workflows/docs.yml:
  • Runs on every push to master and on demand (workflow_dispatch).
  • Builds the workspace with DOCS_BASE_PATH=/get-starknet, uploads docs/dist/public and deploys it with actions/deploy-pages.
  • Workflow-level permissions are contents: read. Only the deploy job gets pages: write / id-token: write.
  • Uses the github-pages environment, which by default only allows deploys from the default branch.
• docs/vocs.config.ts: basePath: process.env.DOCS_BASE_PATH. Only the Pages build sets it, so Vercel and vocs dev keep serving from / until Vercel is retired. Adds @types/node to docs devDependencies for process.
• Markdown outputs (in the workflow):
  • Pages can't rewrite URLs the way vercel.json does, so the workflow copies each page's Markdown from assets/md/ to <page>.md.
  • vocs also writes the links in llms.txt, llms-full.txt and the page Markdown as root-absolute paths that ignore basePath (src/internal/llms.ts), so the workflow adds the base path to them.
• README.md: links to the new URL.

Verification

• pnpm install --frozen-lockfile, format:check, build, typecheck, lint:check, test (50 tests) and actionlint all pass; tsc on docs/ is clean.
• A build without DOCS_BASE_PATH still emits root paths (/assets/…), so the Vercel deployment is unchanged.
• Simulated Pages site: I replayed the workflow's build and Markdown step locally and served the output under /get-starknet/ with a static server.
  • Every asset, the sidebar, top nav and in-page MDX links resolve under the base path.
  • Client-side navigation (RSC payloads), deep links, search and the UI demo modal (dark mode) all work.
  • /get-starknet/llms.txt and /get-starknet/<page>.md return 200, and no unprefixed links remain in the Markdown outputs.

Known gaps with a base path (upstream vocs)

• Ask AI menu: vocs fetches the page Markdown from /assets/md/… without basePath. "View as Markdown" opens a 404, and "Copy page for AI" falls back to copying the page URL. "Open in ChatGPT/Claude" works. The fix is in wevm/vocs#627, still open; bump vocs once it lands.
• "Skip to content" link: links to /#vocs-content without the base path.

Not verified

• The real Pages deploy, which can't run until Pages is enabled. Please check the first run of the Docs workflow and the live site.

Follow-up after the switch

Retire the Vercel project. Either delete it, or replace vercel.json with a permanent redirect to the new URL so old links keep working. Then remove vercel.json.

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

The production Pages deployment requires maintainer verification of admin-controlled settings, the first Docs workflow run, and live routes/assets before Vercel can be retired.

No open issues 🎉

1 file not reviewed

• pnpm-lock.yaml: Generated file

What changed in this PR

Adds GitHub Pages deployment for the documentation site, building on #347’s static Vocs output and preparing the move from Vercel.

Changes:

• Adds a workflow to build and deploy docs on pushes to master or manual runs, with deployment-only write permissions.
• Configures the /get-starknet base path and adjusts generated Markdown files and links for static hosting.
• Updates the README documentation URL and adds Node.js types for the docs configuration.

Pages must be enabled by a repository admin before deployment; the first live deployment remains unverified.

File	Description
README.md	Points readers to the GitHub Pages documentation URL.
pnpm-lock.yaml	Records the docs Node.js types dependency and related peer resolutions.
docs/​vocs.config.ts	Reads the deployment base path from an environment variable.
docs/​package.json	Adds Node.js types for process.env usage.
.github/​workflows/​docs.yml	Builds, prepares Markdown outputs, and deploys the static docs to Pages.

_{Review effort: Balanced}