Docs

The public documentation site at supabase.com/docs. Built with Next.js App Router; content authored as MDX with custom remark/rehype plugins.

Purpose

Hosts every guide and reference page Supabase publishes. Combines hand-written guides under app/guides/, generated reference pages driven by spec files under spec/, and federated content fetched from external repos at build time.

Directory layout

apps/docs/
├── app/                       # Next.js App Router routes
│   ├── guides/                # Hand-authored guides (auth, database, storage, ...)
│   ├── reference/             # Generated reference pages
│   ├── api/                   # API routes (search, embeddings, sitemaps, ...)
│   ├── graphiql/              # GraphiQL playground
│   ├── contributing/          # Contributing surface
│   └── page.tsx               # Landing
├── content/                   # MDX content (some sections)
├── features/                  # Feature modules
│   ├── docs/                  # MDX rendering pipeline, helpers
│   ├── command/               # Command-menu integration
│   ├── ui/                    # Docs-specific components
│   ├── recommendations/       # "Related pages"
│   └── auth/, data/, telemetry/, seo/, directives/
├── spec/                      # SDK / Config / CLI / OpenAPI specs that drive reference pages
├── generator/                 # Builds pages from specs
├── lib/mdx/                   # Custom remark/rehype plugins
├── resources/                 # Static images and downloadable assets
├── scripts/                   # Build helpers (generate sitemaps, prepare content, ...)
└── middleware.ts              # Auth-aware redirects, A/B routing

Guides

app/guides/ is the canonical home for narrative documentation. Top-level sections:

Section	Topic
getting-started/	First-run instructions.
auth/	Auth (GoTrue) configuration and flows.
database/	Postgres usage, extensions, performance.
storage/	File and image storage.
realtime/	WebSocket subscriptions.
functions/	Edge functions.
api/	Auto-generated REST and GraphQL APIs.
graphql/	pg_graphql extension usage.
cron/, queues/	Scheduled jobs and queues.
ai/	AI / vectors / embeddings toolkit.
self-hosting/	The companion to docker/.
local-development/	Supabase CLI workflows.
platform/	Hosted-platform features (orgs, billing, branches).
security/, telemetry/, troubleshooting/, integrations/, deployment/, resources/	Cross-cutting topics.

Reference

Reference pages are generated. The driver is a set of YAML / JSON specs under apps/docs/spec/:

• OpenAPI for HTTP APIs.
• SDKSpec (custom) for client libraries.
• ConfigSpec for tool configuration options.
• CLISpec for CLI commands.

apps/docs/generator/ reads the specs and produces React pages at build time. To update reference content, edit the spec, never the rendered page.

Versioning: each tool has matching <tool>_versioned_docs/ and <tool>_versioned_sidebars/ directories so multiple versions can be published in parallel. npm run cli:version 1.2.3 cuts a new version (per apps/docs/README.md).

Federated docs

Content from external repos (e.g. supabase/vecs) can be pulled in at build time via Next.js's getStaticProps and rendered as native docs pages. Implementation lives in apps/docs/lib/mdx/ (link rewriting via rehypeLinkTransform.ts, mkdocs syntax via remarkAdmonition.ts, etc.). See DEVELOPERS.md for the rationale and apps/docs/app/guides/ai/python/[slug]/ as a reference implementation.

Search and AI

• app/api/ includes Supabase-hosted endpoints for embedding-based search (packages/ai-commands is used here).
• search.yml workflow rebuilds the embeddings index periodically.
• The on-page command menu is wired through features/command/.

Middleware

middleware.ts is non-trivial — it handles dev-only auth (features/dev-secret-auth/), redirects, and incoming-link rewrites. It is unit-tested via middleware.test.ts.

Build pipeline

Contentlayer is not used in the docs site (unlike design-system and ui-library). MDX is processed at build time by Next.js with the plugin chain in lib/mdx/.

scripts/ contains:

• pnpm generate:types — sync Supabase database types.
• pnpm api:codegen — refresh OpenAPI types (in packages/api-types).
• Scheduled syncers (docs-sync.yml, docs-mgmt-api-update.yml, docs-js-libs-update.yml).

Testing

• pnpm test:docs runs Vitest.
• docs-tests-smoke.yml runs a fast subset on every PR.
• docs-lint-v2.yml runs supa-mdx-lint.

Integration points

• Pulls API types from packages/api-types for the auto-generated reference.
• Uses packages/ai-commands for embeddings / search.
• Shares UI with packages/ui and packages/icons.
• Pulls in static fixtures and SDK metadata from packages/shared-data.

Entry points for modification

• Add or edit a guide → drop an MDX file in app/guides/<section>/<slug>.mdx.
• Add a redirect → use the docs-specific redirects (typically next.config.mjs); compare with apps/www/lib/redirects.js for marketing-side rules.
• Add or update reference content → edit the relevant spec under apps/docs/spec/ and rerun the build.
• Federate a new external doc set → mirror the pattern under app/guides/ai/python/[slug]/.