Publish Skills documentation with VitePress and Cloudflare Pages (#143)

Publish the Skills extension as a browsable VitePress site on Cloudflare
Pages, using the same documentation theme as ext-tasks and reusing the
existing source documents.

- Follow the Tasks site's structure: a substantive overview at `/` and a
separate stable specification page. The small `index.md` uses native
VitePress includes to reuse excerpts from the released specification,
rather than duplicating its prose.
- Link to the condensed overview on the MCP website.
- Render `specification/stable/skills.mdx` through a small Markdown
include, preserving the released specification unchanged.
- Add local search, section outlines, MCP branding, source edit links,
and a Specification navigation item with a Stable sidebar entry. Keep
the full specification at `/specification/stable/skills`.
- Build pull requests, including fork contributions, in read-only GitHub
Actions CI.
- Use the existing Cloudflare Pages Git integration for publishing.
Remove the GitHub Pages deployment workflow and project-path
configuration.

## Validation

- `npm run docs:build` passed with VitePress 1.6.4.
- Checked that the build emits an overview and a separate specification
page; verified included excerpt boundaries, internal links and anchors,
specification source edit links, and the rendered MDX callout.
- `git diff --check` passed.
- The build emits the existing large-chunk warning from the diagram
dependencies.
- Cloudflare deployment itself has not been run from this workspace.

## Publishing settings

DNS and Cloudflare Pages setup are ready separately. The existing Pages
project should use:

| Setting | Value |
| --- | --- |
| Repository | `modelcontextprotocol/ext-skills` |
| Production branch | `main` |
| Root directory | Repository root |
| Build command | `npm run docs:build` |
| Build output directory | `.vitepress/dist` |
| Node.js | `22` (set `NODE_VERSION=22` in Pages) |
| Custom domain | `skills.extensions.modelcontextprotocol.io` |

Cloudflare installs dependencies and builds from the committed npm
lockfile. The site is served at the domain root with clean URLs.
Publishing is handled by Cloudflare's connected Git integration; no
GitHub Pages environment, Pages permissions, or Cloudflare deployment
secrets in GitHub Actions are required.

After merge, verify the production deployment and custom domain in the
existing Cloudflare Pages project. One-time publishing instructions stay
in this PR description, not in a checked-in setup document.

Fork PRs receive the CI build check. Automated Cloudflare previews for
forks require the separately discussed trusted artifact-publishing
workflow; this PR does not add that workflow.

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
This commit is contained in:
Sambhav Kothari 2026-09-16 17:06:02 +02:00 • committed by GitHub
commit 41e7c66db2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

22
.github/workflows/ci.yml vendored Normal file
View file

@ -0,0 +1,22 @@
name: CI
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
docs:
name: Build documentation
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run docs:build