Nextra Docs

nextra-docs

Vercel's Nextra Docs Starter Kit — five MDX pages, a sidebar ordered by _meta, an About page and an external Contact link in the navbar, an interactive counter, full-text search — running on Cloudflare Workers + Static Assets through @opennextjs/cloudflare, and packaged as an Orun baseline: one command takes a new docs site from nothing to live on stage and prod, in its own repository, under its own name.

The template's content is the content. The upstream is Nextra 2 on Next 13's pages router, which the OpenNext adapter cannot build, so the same pages, sidebar, theme settings and counter component are expressed through Nextra 4 on the App Router (a content/ directory, a [[...mdxPath]] gateway, _meta.ts, Pagefind search). What the port adds is the Workers build, the monorepo wrapper, a test package, and the deploy contract. What the baseline adds is everything needed to make a copy of it somebody else's — built the way cirrus-baseline is, with the repository conventions it shares: an Orun intent, one component per deployable, credential-free checks on every pull request, and an Orun pipeline that deploys on merge. See specs/epics/nextra-docs for the design (including the Nextra 2 → 4 mapping, file by file), the milestones and the as-built status.

Instantiating a site

git clone --depth 1 --branch <baseline-tag> https://github.com/sourceplane/nextra-docs
cd nextra-docs
orun new --blueprint repo-blueprint.yaml --out ~/sites/acme-docs --run-hooks --resume \
  --set reponame=acme-docs --set productname="Acme Docs" \
  --set githuborg=acme-inc --set subdomain=<workers-dev-subdomain>

Or, once the platform's registry lists it, from the Orun console (Baselines → nextra-docs → Build). Two phases — 01-product (the repository created, then the whole site in one pull request, deployed to stage and prod and smoke-tested) and 03-docs (the live deployment recorded) — each landing one pull request in the new repository. BOOTSTRAP.md is the operator guide; docs/phases/ has a page per phase.

The new repository receives the site only — the app, its tests, its CI, its tooling, a README of its own and its operating contract — renamed throughout to the site's name, repository and Cloudflare Worker. None of this repository's machinery ships.

What is here (the site)

Getting started

pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build            # next build + pagefind + opennextjs-cloudflare build → apps/web/.open-next

Develop with Next's dev server, or preview the real Worker output locally:

pnpm --filter @app/web dev        # http://localhost:3000 (no search index until a build has run)
pnpm --filter @app/web preview    # wrangler dev over .open-next/worker.js

Add a page by dropping an .mdx file into apps/web/content/ and naming it in content/_meta.ts (or leave it out of _meta to sort it after the named ones); it is pre-rendered and indexed at build time.

How it maps to Vercel

CI