Vercel
The layer is built for Vercel: rendered pages are cached at the edge with ISR, parsed content persists in the Runtime Cache across deployments, and a GitHub webhook purges pages the moment content changes.
Setup
Import the repository
Create a Vercel project from your docs repository. If the Nuxt app lives in a subdirectory (for example docs/), set it as the project's Root Directory.
Set the environment variables
In the project's Settings → Environment Variables:
| Variable | Purpose |
|---|---|
GITHUB_TOKEN | Reads content from GitHub and queries the GraphQL API for page history and RSS. A fine-grained token with read access to the repository contents is enough. |
WEBHOOK_SECRET | Shared secret that signs the push webhook. Generate a random string. |
VERCEL_BYPASS_TOKEN | Lets the revalidation endpoint purge ISR pages. Must be available at build time — it's baked into the deployment's ISR configuration, so a runtime-only value leaves purging broken. |
NUXT_OG_IMAGE_SECRET | Signs OG image URLs. Generate a random string. |
VERCEL_AUTOMATION_BYPASS_SECRET is set automatically when Deployment Protection is enabled; it lets the revalidation endpoint call back through the protection wall.
Add the push webhook
In your GitHub repository, go to Settings → Webhooks → Add webhook:
- Payload URL:
https://your-docs-domain.com/api/revalidate - Content type:
application/json - Secret: the same value as
WEBHOOK_SECRET - Events: just the push event
On every push to the production branch, the endpoint verifies the signature, resolves the new content commit, and purges exactly the pages that changed. Content is live within seconds — see Architecture.
Skip builds for content pushes
Since content never ships in the build, a push that only touches content/ doesn't need a deployment — the webhook already handles it. Tell Vercel to skip those builds with an Ignored Build Step:
In Settings → Git → Ignored Build Step, select Custom and set:
git diff --quiet HEAD^ HEAD -- ':!content'The command exits 0 (skip the build) when nothing outside content/ changed. Alternatively, version it in vercel.json at the project root:
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"ignoreCommand": "git diff --quiet HEAD^ HEAD -- ':!content'"
}Adjust the path if your content directory differs. Both setups behave the same; the dashboard setting applies without a file in the repository, while vercel.json travels with the code.
ISR behavior
The layer generates ISR route rules for every top-level content section, the landing page, previews, and the machine-readable routes (/raw/**, /llms.txt, /rss.xml). Pages expire after 300 seconds by default, or immediately when the webhook purges them.
Tune or disable this with comarkDocs.isr in nuxt.config.ts. Your own routeRules take precedence over the generated ones.
Rolling back content
Content follows the head of the production branch, not the deployment — so rolling back a deployment in Vercel does not roll back content. Instead, roll back content with git:
git revert <bad-commit>
git pushThe webhook picks it up like any other push, and the Ignored Build Step means the revert doesn't trigger a build either. To inspect what any older version looked like before reverting, open it at /blob/<sha>.
Next steps
- PR preview comments — post
/tree/preview links on content pull requests automatically.