Configuration reference
Every variable and secret your docs site understands, in one place.
Configuration lives in two places: non-secret vars in wrangler.jsonc
(committed to your repo), and secrets set with wrangler secret put NAME
(or in your Worker's dashboard under Settings → Variables and Secrets). For
local development, put secrets in a .dev.vars file (never committed).
Variables (wrangler.jsonc → vars)
| Variable | Purpose |
|---|---|
GITHUB_OWNER / GITHUB_REPO / GITHUB_BRANCH | Where the editor publishes — point these at your repo and default branch. |
DOCSDEV_SITE_ID | Enables team sign-in. When set, it's the only sign-in method. Empty = standalone mode. |
DOCSDEV_ISSUER | The docs.dev service origin (leave the default unless self-hosting the service). |
AI_TEXT_MODEL / AI_IMAGE_MODEL | Override the Workers AI models used by the editor. |
HOME_REDIRECT_TO_DOCS | Set to "true" to skip the landing page — / redirects straight to /docs. Offered as an option when you first deploy with the Deploy to Cloudflare button; change it later in wrangler.jsonc (applies on the next push) or in the dashboard (applies immediately). |
Secrets
| Secret | Needed for |
|---|---|
GITHUB_PAT | Publishing from PIN/docs.dev sessions and the shared-drafts store. Fine-grained token, contents: read/write on the docs repo. |
ADMIN_PIN + ADMIN_SECRET | PIN sign-in. Both required; no defaults — editing stays disabled without them. |
GITHUB_APP_CLIENT_ID + GITHUB_APP_CLIENT_SECRET | GitHub sign-in. |
TAVILY_API_KEY or BRAVE_API_KEY | Optional web-search grounding for AI writing. |
Bindings (wrangler.jsonc)
| Binding | Purpose |
|---|---|
AI (Workers AI) | AI writing & images in the editor and the reader-facing Ask AI assistant. Included by default; remove it and both features hide themselves. |
INSIGHTS (D1, optional) | Ask AI insights — logs reader questions anonymously so admins can see what the docs couldn't answer. Off until you create the database and uncomment the block: |
npx wrangler d1 create docsdev-insights
# paste the returned id into the d1_databases block in wrangler.jsoncSign-in precedence
DOCSDEV_SITE_IDset → docs.dev team sign-in only. PIN and GitHub sign-in are disabled, so stale credentials can't bypass team membership.- Otherwise → whichever of GitHub sign-in and PIN you've configured (both is fine). Nothing configured = editing disabled, docs still served.
Commands
pnpm dev # local dev server
pnpm types:check # frontmatter + type validation — run before pushing
pnpm cf:preview # build and run the real Worker locally
pnpm cf:deploy # manual deploy (normally unnecessary — pushing deploys)CI (Workers Builds)
The one-click deploy configures these automatically; if you're setting up CI by hand, use:
- Build command:
npx opennextjs-cloudflare build - Deploy command:
npx wrangler deploy