<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Stack
Draft stack extracted from `docs/monitoring`. Merge bottom-up. The
troubleshooting *catalog* rewrite (`content/troubleshooting` and the
Diagnosing UI) stays out of scope.
1. #49503 move inspect and advisors
2. #49501 split Studio logs from ClickHouse queries
3. #49500 treat reports as signal dashboards
4. #49502 add Observe the data hub
5. #49506 add agent setup components
6. #49504 add hire-an-agent templates
7. **#49505** restructure observability nav, overview, Detecting, and
flatten Observe the data ← **this PR**
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Docs update. Top layer in the observability stack.
## What is the current behavior?
The section is still titled Monitoring and Debugging, with a Debugging /
Monitoring split that does not match the new pages. The debugging guide
is still the master layer-isolation + symptom table. Observe the data is
split into “what data” vs “where to observe it,” which duplicates the
source pages.
## What is the new behavior?
- Section title is Observability
- Overview groups Observe the data, Detect and resolve, Hire an agent,
and Export
- **Observe the data is flattened by source.** Logs, Metrics API,
Database, Advisors, and Reports each list where to read that source.
There is no separate MCP/API/CLI/Studio nav group.
- **Observe vs Detecting:** Observe is the catalog (what exists, how to
access it). Detecting is how to *use* those sources to pick up a Health
/ Security / Performance / Usage signal. Named errors skip to
Diagnosing.
- Studio Logs sits under Logs. Reports sits beside the other sources.
- Troubleshooting stays in the global menu and also appears as
Diagnosing under Detect and resolve
## Additional context
This is the last PR in the stack. Together the seven PRs reconstruct the
`docs/monitoring` observability IA and guide content, without shipping
the troubleshooting catalog overhaul.
<!-- CURSOR_AGENT_PR_BODY_END -->
<div><a
href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a
href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div>
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com>
Co-authored-by: Nik Richers <nik@validmind.ai>
Wire middleware sdk docs (`@supabase/middleware`)
https://github.com/supabase/middleware
Preview ref here:
https://docs-git-docs-supabase-middleware-sdk-supabase.vercel.app/docs/reference/middleware/introduction
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added a Middleware SDK reference section to the documentation.
* Added installation guidance for npm, Yarn, pnpm, Deno, and Bun.
* Documented framework-agnostic middleware composition, typed shared
context, ordering, trust, and environment access across supported
runtimes.
* Added Middleware documentation to navigation and search.
* Identified the Middleware SDK as an alpha release.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What kind of change does this PR introduce?
Docs update / follow-up to #48379.
## What is the current behavior?
`/guides/resources` and `/guides/getting-started` hand-roll `GlassPanel`
grids in MDX. They look like ContentListings cards after the chrome PR,
but they do not use the shared data files, so they miss PostHog
`docs_content_listing_clicked` telemetry and the CONTRIBUTING
contribution path.
## What is the new behavior?
Those pages use `<ContentListings id="…" />` backed by
`resources.data.ts` and `getting-started.data.ts`, same pattern as
storage.
- Section-level `$Show` wrappers stay for framework / web / mobile
blocks
- Nimbus stays a `$Partial` behind `$Show`
- New optional per-item `feature` field gates SDK links (e.g. Flutter /
Swift / Kotlin) without splitting whole sections
- CONTRIBUTING notes when to use `feature` vs a partial-level `$Show`
## To test
Compare the following against `master`:
-
[Resources](https://docs-git-dnywh-docs-content-listings-resources-239158-supabase.vercel.app/docs/guides/resources):
overview, migrate, and postgres grids; icons in light/dark
- [Getting
started](https://docs-git-dnywh-docs-content-listings-resources-239158-supabase.vercel.app/docs/guides/getting-started):
overview, use cases, framework quickstarts, web demos, mobile tutorials;
nimbus partial when enabled
- Click a card and confirm `docs_content_listing_clicked` fires with the
expected `listingId`
Everything should look and feel the same. It’s just that we’re using
`ContentListings` instead of `GlassPanel` grids.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Added centralized Getting Started and Resources content listings,
including quickstarts, demos, tutorials, migration guides, and Postgres
resources.
- Added feature-based visibility controls for individual content listing
items.
- **Improvements**
- Disabled content is now automatically hidden from documentation pages
and generated Markdown.
- Pages and sections with no available content are omitted entirely.
- External documentation links are more secure.
- Updated contribution guidance with instructions and examples for
feature flags.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What kind of change does this PR introduce?
Bug fix / docs UI polish.
## What is the current behavior?
- Many docs `GlassPanel`s use `background={false}`, so hover only tweaks
the border and reads as having no hover state
- Compact icon+label grids still use `IconPanel`, which has a broken
`-z-10` hover fill and overlaps with the newer `IconLink` pattern
- Description card grids jump to 3-up too early on medium widths
## What is the new behavior?
**GlassPanel**
- Removes the `background` prop; cards always use the filled surface
with stronger border hover
- Tightens icon→description gap (`gap-6` → `gap-3`)
- Decorative icons/logos use empty `alt` so screen readers don’t hear
the title twice
**Icon tiles**
- Retires `IconPanel` from docs and deletes it from `ui-patterns`
- Uses `IconLink` / `IconLinkList` for compact navigation tiles (auth
providers, social login, etc.)
- Adds `IconLinkButton` for SMS provider pickers (same chrome, opens a
dialog)
- Adds focus styles, list labelling, and dialog-trigger ARIA where
needed
**Layout / content**
- Migrate-to-Supabase description cards on resources use `GlassPanel`
(not slim icon tiles)
- Grid spans use `md:… xl:…` so cards stay 2-up until ~1280px
- Fixes migrate links to `/guides/platform/migrating-to-supabase/…` and
SSR quickstarts to `creating-a-client` with framework query params
- Moves the Extensions list `key` onto the outer `Link`
| Before | After |
| --- | --- |
| <img width="1185" height="1323" alt="Resources Supabase Docs"
src="https://github.com/user-attachments/assets/1677bf65-d3a3-4202-8c70-e758f7c3bcce"
/> | <img width="1185" height="1323" alt="Resources Supabase Docs"
src="https://github.com/user-attachments/assets/51760f0f-62b6-4010-9841-de26039f37b4"
/> |
## Additional context
Homepage compact sections already use `IconLinkList` from #48317; this
PR finishes that pattern for remaining docs `IconPanel` callsites and
cleans up GlassPanel hover.
`www/customers` only drops the removed `background` prop; those cards
already use the filled surface via `logo`.
## Test plan
- [ ] `/guides/getting-started`: GlassPanels show filled surface and
clearer border hover
- [ ] `/guides/resources`: migrate cards are GlassPanels with working
`/platform/…` links; 2-up until xl
- [ ] `/guides/auth/social-login` and auth providers partial: IconLink
tiles hover/focus correctly
- [ ] `/guides/auth/phone-login`: SMS provider buttons open dialogs;
keyboard focus works
- [ ] Docs homepage: migrate / self-host IconLinkLists unchanged in
behaviour
- [ ] `/guides/auth/server-side`: Next.js / SvelteKit cards resolve on
docs preview
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Improved Layouts**
* Made “GlassPanel” card grids more responsive and consistent; refined
card and success badge spacing for a cleaner presentation.
* **Updated Documentation**
* Refreshed multiple guide and resource pages (including quickstarts and
migration content) with standardized card layouts and updated link
destinations.
* **Component Updates**
* Standardized “GlassPanel” styling (background toggle removed) and
simplified icon-based panels; added an `IconLinkButton` for action
tiles; updated authentication provider grids to use the shared tile UI.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Reverts supabase/supabase#48144
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Documentation generation now surfaces missing or unreadable AI skills
and Terraform schema data instead of silently producing empty sections.
* This improves visibility into incomplete documentation builds and
helps ensure generated reference content is available and accurate.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Ali Waseem <waseema393@gmail.com>
<!-- ccr-slack-attribution -->
_Requested by **Ivan Vasilov** · [Slack
thread](https://supabase.slack.com/archives/C0161K73J1J/p1784639352877839?thread_ts=1784625513.046239&cid=C0161K73J1J)_
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Bug fix.
## What is the current behavior?
Running `pnpm --filter=docs run build:guides-markdown` standalone — as
`apps/www`'s prebuild does, without first running
`build:federated-content` — crashes with `ENOENT ... ai-skills.json`
(and the equivalent for `terraform.schema.json`).
The `AiSkillsIndex` and `TerraformProviderSchema` markdown-schema
handlers `readFileSync` a gitignored, build-time-generated JSON artifact
unconditionally. In the full docs build these files exist because
`build:federated-content` runs first (via the docs `prebuild`), but in
the standalone / www path they do not, so the read throws.
These unguarded reads were introduced in #48045 (ai-skills) and #48010
(terraform), which surfaced as the www Vercel build failure.
## What is the new behavior?
Both handlers now render an empty section (return an empty string) when
the generated artifact is absent, so `build:guides-markdown` succeeds in
the standalone / www path.
When the artifact IS present (the full docs build, which runs
`build:federated-content` first), behavior is byte-for-byte unchanged —
the file is parsed and rendered exactly as before. The full docs build
is not affected.
## Additional context
Implemented with a minimal `existsSync` guard (from the already-imported
`node:fs`) in each handler:
- `apps/docs/internals/markdown-schema/AiSkillsIndex.ts`
- `apps/docs/internals/markdown-schema/TerraformProviderSchema.ts`
No changes to any `package.json`, `.gitignore`, or the generators — the
fix is confined to the two handlers.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01RynCtzP874KrpN8CPf7n7n)_
Co-authored-by: Claude <noreply@anthropic.com>
Add a `server` entry to the reference-markdown pipeline so it emits
`public/markdown/reference/server.md`, and register the Supabase Server
Library Reference as a source in the www `llms.txt` and `llms-full.txt`
routes.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added a new Supabase Server Library Reference covering server-side SDK
usage.
* Included the server reference in generated documentation and plaintext
documentation indexes.
* Made server SDK reference content available through the full
documentation feed.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added new public MCP base URL environment variables for hosted and
self-hosted setups.
* Introduced reusable MDX components to render custom MCP configuration
content.
* **Documentation**
* Updated the MCP guide to reference shared MCP server template values
for examples.
* Swapped the CI configuration example for a component-rendered snippet
for consistency.
* **Bug Fixes**
* Improved self-hosted MCP base URL fallback so it prefers the new
non-platform URL when no custom API URL is provided.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
update pg changes documentation
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated the Realtime Postgres Changes guide with a new, generalized
“Listening to specific events” section (including INSERT/UPDATE/DELETE/*
examples) and standardized `event` usage.
* Refreshed “Available filters” with a unified filter builder approach,
expanded operator reference, consistent Filter-string/tab patterns,
`not.` and `AND` guidance, and clearer limitations (including
delete-event filtering).
* Updated “Selecting specific columns” examples to match the latest
payload/subscription guidance.
* **Refactor**
* Simplified the Realtime limits estimator by removing filter-based
throughput inputs and related UI/table columns; throughput is now based
on compute add-on, RLS, and concurrency.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## What
Routes the **Dart/Flutter v2** reference through the new
reference-content pipeline (`scripts/build-reference-content.ts` +
`spec/reference/dart/v2/`), the same one JavaScript v2 already uses.
Dart v1 stays on the legacy YAML pipeline.
## How
Dart has no upstream TypeDoc dump, so this follows the reference
README's "adapt other formats as a pre-step" approach:
- **`scripts/generate-dart-reference.ts`** converts the committed legacy
spec (`spec/supabase_dart_v2.yml`) plus the shared section tree into a
TypeDoc-shaped dump at `spec/reference/dart/v2/supabase_flutter.json`
(gitignored, like every other dump). Each Dart method becomes a
`variant: 'declaration'` node tagged with `@category`/`@subcategory` and
carries the legacy function shape (description, notes, params, examples)
on a non-TypeDoc `content` field.
- **`build-reference-content.ts`** gains a small, backward-compatible
addition: it spreads a declaration's `content` straight onto the
`functions.json` entry. The renderer then shows params/examples/notes
exactly as the legacy YAML did, with no typeSpec round-trip. The field
is absent for real TypeDoc dumps, so **JavaScript output is unchanged**
(existing JS snapshot still passes).
- `dart-v2` added to `SUPPORTS_NEW_REFERENCE_PROCESS`; the v2 `specFile`
is dropped from the nav entry so the legacy generator skips it.
- Dart search ingest switched to the new-pipeline loader.
- `config.json` + hand-authored partials (intro markdown,
`initializing`, and subcategory overviews like `using-filters`,
`auth-mfa`) added under `spec/reference/dart/v2/partials/`, mirroring
the JS lib.
- The dart dump is regenerated in `codegen:references:new` and in CI; a
self-contained `dart/v2` snapshot test covers the full YAML → dump →
content path.
## Verification
- `vitest run scripts/build-reference-content.test.ts` — both JS and
Dart snapshots pass.
- 112 function sections all resolve to renderable `functions.json`
entries (104 methods + 7 subcategory overviews + `initializing`).
- `tsc --noEmit` clean for all changed files.
- Legacy generator confirmed to skip dart v2 (only `dart.v1.*`
regenerated).
> Note: the live dev server (which needs the Supabase backend) was not
run; verification was done at the data-pipeline level plus parity with
the production JS pipeline behavior.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added Dart v2 reference documentation sections, including Installing,
Initializing, Filters, Modifiers, Auth Admin, MFA, Passkeys, File
Buckets, Introduction, and Upgrade guidance.
* Expanded the Dart v2 reference pipeline so Dart API pages are
generated from the newer reference content flow.
* **Bug Fixes**
* Improved Dart reference rendering by preserving legacy descriptions,
notes, params, and examples in generated function entries.
* Updated Dart v2 reference search to use the new pipeline’s generated
content so results and navigation stay in sync.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Renders the MCP config component as markdown for static markdown builds.
Currently we have no special case for `<McpConfigPanel />`, so it gets
stripped out during markdown rendering. This adds a static markdown
version of this component that renders all agents/tools consecutively.
Adds a new `McpConfigPanel.md.tsx` component that reuses data structures
used by `McpConfigPanel.tsx` but renders as markdown instead of React.
Instead of building the markdown via string concatenation, we use
[supabase-community/mdast-jsx](https://github.com/supabase-community/mdast-jsx)
which allows you to author markdown using JSX (providing type safety,
better DX, maintainability). E.g.
```jsx
<code lang="json" value='{ "key": "value" }' />
```
produces:
````md
```json
{ "key": "value" }
```
````
## Preview
https://docs-git-feat-mcp-config-markdown-supabase.vercel.app/docs/guides/ai-tools/mcp.md
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Summary by CodeRabbit
- **New Features**
- Added a docs-only MCP configuration panel with client-specific setup
steps, deep links, and generated configuration snippets.
- Enhanced guide generation to render richer, component-produced
markdown content.
- **Bug Fixes**
- Improved MCP config serialization and display for consistent
JSON/YAML/TOML output.
- **Refactor**
- Centralized MCP client metadata, instruction content, and config
build/serialization logic for reuse.
- **Chores**
- Expanded package exports for MCP URL builder assets and utilities;
improved runtime code-block language validation and updated PNG asset
typing.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
## I have read the CONTRIBUTING.md file.
YES
## What kind of change does this PR introduce?
This PR helps standardise link sections which is useful for overview
pages that frequently use similar sections such as "Next steps", "Get
started", or "Examples".
Six high-traffic overview pages are migrated as a pilot, with a skill in
the new
[supabase/docs-agent-skills](https://github.com/supabase/docs-agent-skills)
repo to audit and convert the rest in a follow-on PR.
Refactored from an initial YAML front matter approach per review
feedback from @jeremenichelli. Now implemented as a React component and
using existing linting & Markdown export functionality.
A second round of review feedback further simplified the architecture:
the per-listing component registry was removed in favor of a single
`<ContentListings id="..." />` component backed by an ID-keyed data
lookup, the listing data moved out of `apps/docs/components/` into
`apps/docs/data/content-listings/`, the listing-specific link wrapper
was replaced with the existing `<Link>` + `<GlassPanel>` pattern from
the rest of the docs, and the headings now defer to the shared
`<Heading>` from `MdxBase.shared.tsx` (no parallel marker-to-tag
mapping, no typography overrides). Great feedback, thank you! 🙏
Relates to DOCS-1032.
## What is the current behavior?
Authors implement these sections however they wish. As a result,
overview and index pages use inconsistent patterns for orientation
links: some use hand-rolled Markdown lists, some use custom panel/grid
components, some use buttons, and some have no guidance about where to
go next at all. There is no shared component for these sections and no
analytics on those clicks.
## What is the new behavior?
Authors add orientation sections in two steps:
1. Define listing data in a `.data.ts` file under
`apps/docs/data/content-listings/` (for example, `storage.data.ts`).
Each `ContentListingGroup` has a globally-unique `id` like
`storage-get-started`.
2. Place a single `<ContentListings id="..." />` component inline in
guide MDX.
The ID is also the telemetry `listingId`, so the same value
disambiguates the section in PostHog dashboards.
Grid and list layouts, optional icons (such as
`/docs/img/icons/github-icon` with `-light.svg` variants for dark mode),
and external URLs are supported. Conditionals that use `$Show` around
inline components are also supported, for example for auth pricing.
### Usage example from "Storage" overview page
`apps/docs/data/content-listings/storage.data.ts`:
```ts
export const storageGetStarted: ContentListingGroup = {
id: 'storage-get-started',
heading: 'Get started',
description: 'Choose the bucket type that fits your use case:',
type: 'grid',
items: [
{
title: 'Files buckets',
href: '/guides/storage/quickstart',
description:
'Store and serve images, videos, documents, and general-purpose files with direct URL access and row-level security.',
},
{
title: 'Analytics buckets',
href: '/guides/storage/analytics/introduction',
description:
'Store data in Apache Iceberg tables for data lakes, logs, and ETL. Query from Postgres via foreign tables with partitioning.',
},
{
title: 'Vector buckets',
href: '/guides/storage/vector/introduction',
description:
'Store embeddings and run similarity search for semantic matching, AI, and RAG. Use HNSW indexing, distance metrics, and metadata filtering.',
},
],
}
```
`apps/docs/content/guides/storage.mdx`:
```mdx
<ContentListings id="storage-get-started" />
```
Renders as:
<img width="689" alt="Storage Get started listing — Files, Analytics,
and Vector buckets"
src="https://github.com/user-attachments/assets/0d1b9531-962f-40ae-891e-b1e93ff1c939"
/>
<br>Exported in Markdown as:
```md
## Get started
Choose the bucket type that fits your use case:
- **[Files buckets](/docs/guides/storage/quickstart):** Store and serve images, videos, documents, and general-purpose files with direct URL access and row-level security.
- **[Analytics buckets](/docs/guides/storage/analytics/introduction):** Store data in Apache Iceberg tables for data lakes, logs, and ETL. Query from Postgres via foreign tables with partitioning.
- **[Vector buckets](/docs/guides/storage/vector/introduction):** Store embeddings and run similarity search for semantic matching, AI, and RAG. Use HNSW indexing, distance metrics, and metadata filtering.
```
Click tracking fires via PostHog (`docs_content_listing_clicked`):
```json
{
"action": "docs_content_listing_clicked",
"custom_properties": {
"targetPath": "/guides/storage/quickstart",
"linkTitle": "Files buckets",
"groupTitle": "Get started",
"listingId": "storage-get-started"
}
}
```
Still finding my way around PostHog, but I verified on preview deploy
that clicking a content listing on `/docs/guides/auth` sends
`docs_content_listing_clicked` to
`https://api.supabase.green/platform/telemetry/event` and receives HTTP
201.
### Authoring experience
Three ways to add or convert content listings: copy the agent prompt
first, use snippets for manual edits, or invoke the audit skill for
batch follow-on work. Refer to `CONTRIBUTING.md` for the full authoring
guide.
#### 1. Agent prompt
Copy into Cursor or another AI assistant:
```text
Add a content listing block for [TOPIC] / [SECTION] (for example, Storage / Examples).
Follow CONTRIBUTING § Content listings in apps/docs.
- Add data to apps/docs/data/content-listings/[topic].data.ts
- Use a globally-unique kebab-case id like `[topic]-[section]`
- Place inline in the guide MDX with <ContentListings id="..." />
- Copy structure from storageGetStarted in apps/docs/data/content-listings/storage.data.ts
- Run pnpm test:local lib/content-listings.test.ts from apps/docs
```
#### 2. VS Code / Cursor snippets
Type these prefixes in the docs workspace
(`.vscode/content-listing.code-snippets`):
| Prefix | Inserts |
| ----------- | --------------------------------------------------------
|
| `cl-data` | `ContentListingGroup` export skeleton with namespaced id |
| `cl-inline` | `<ContentListings id="…" />` in guide MDX |
<img width="658" height="274" alt="image"
src="https://github.com/user-attachments/assets/5ef20954-7aee-4925-887d-79a5ae766b37"
/>
#### 3. Batch audit skill
For follow-on overview page conversion or maintenance, use the
[`audit-content-listings`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/audit-content-listings/SKILL.md)
skill in `docs-agent-skills` (skill, `conversion-manifest.json`, and
validation script).
Example:
```text
Use audit-content-listings. Audit getting-started.mdx, update conversion-manifest.json, then convert the next unconverted section only.
```
## Additional context
The implementation includes a presentational `<ContentListings />`
component (grid/list layouts, GlassPanel, telemetry) backed by ID-keyed
data modules, and a single markdown export handler that reads the same
`id` prop from the JSX and looks up data via the shared registry.
Key files:
- **Data:** `apps/docs/data/content-listings/` (one `.data.ts` file per
guide topic, plus `index.ts` exporting `CONTENT_LISTINGS` and
`getContentListingById`)
- **Renderer:** `apps/docs/components/ContentListings/` (single
`<ContentListings id="…" />` component); registered in
`apps/docs/features/docs/MdxBase.shared.tsx`
- **Types/helpers:** `apps/docs/lib/content-listings.schema.ts` (zod
schemas, type aliases, grid/heading/href helpers)
- **Markdown export:** `apps/docs/internals/markdown-schema/Listings.ts`
(single ID-driven handler) wired into
`apps/docs/internals/generate-guides-markdown.ts`
- **Telemetry:** `docs_content_listing_clicked` defined in
`packages/common/telemetry-constants.ts`, fired from
`ContentListings.client.tsx`
- **Authoring guide:** `apps/docs/CONTRIBUTING.md` (Components and
elements → Content listings)
- **VS Code snippets:** `.vscode/content-listing.code-snippets`
(`cl-data`, `cl-inline`)
### Before & After
#### Auth
| [Before (production)](https://supabase.com/docs/guides/auth) | [After
(preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/auth)
|
|
---------------------------------------------------------------------------------------------------------------------------
|
---------------------------------------------------------------------------------------------------------------------------
|
| 
| 
|
#### Database overview
| [Before
(production)](https://supabase.com/docs/guides/database/overview) |
[After
(preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/database/overview)
|
|
--------------------------------------------------------------------------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------------------------------------------------------------------------
|
| 
| 
|
#### Edge Functions
| [Before (production)](https://supabase.com/docs/guides/functions) |
[After
(preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/functions)
|
|
--------------------------------------------------------------------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------------------------------------------------------------------
|
| 
| 
|
#### Storage
| [Before (production)](https://supabase.com/docs/guides/storage) |
[After
(preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/storage)
|
|
----------------------------------------------------------------------------------------------------------------------------------------
|
----------------------------------------------------------------------------------------------------------------------------------------
|
| 
| 
|
#### Realtime
| [Before (production)](https://supabase.com/docs/guides/realtime) |
[After
(preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/realtime)
|
|
-------------------------------------------------------------------------------------------------------------------------------------------
|
-------------------------------------------------------------------------------------------------------------------------------------------
|
| 
| 
|
#### Getting Started (partial migration for demoing)
| [Before
(production)](https://supabase.com/docs/guides/getting-started) | [After
(preview)](https://docs-git-fork-nrichers-nikrichers-docs-1032-sta-e2a8cb-supabase.vercel.app/docs/guides/getting-started)
|
|
------------------------------------------------------------------------------------------------------------------------------------------------------
|
------------------------------------------------------------------------------------------------------------------------------------------------------
|
| 
| 
|
### Test plan
- [ ] Visually verify migrated pages render correctly:
- [ ] `/guides/auth` — grid "Get started", conditional pricing list,
grid "Next steps"
- [ ] `/guides/database/overview` — get started + next steps listings
- [ ] `/guides/getting-started` — top 3-column grid
- [ ] `/guides/functions` — get started + example listings
- [ ] `/guides/storage` — get started, examples, resources listings
- [ ] `/guides/realtime` — get started, examples, resources listings
- [ ] Confirm listings render at explicit page positions
- [ ] Click a content listing link and verify
`docs_content_listing_clicked` fires in PostHog with expected properties
(the new `listingId` is the namespaced kebab-case id, e.g.
`storage-get-started`)
- [ ] Build docs and confirm `.md` alternate output includes listing
sections at component placement (e.g.
`public/markdown/guides/storage.md`)
- [ ] Run unit tests: `pnpm test:local lib/content-listings.test.ts` in
`apps/docs`
## Summary by CodeRabbit
## Release Notes
* **New Features**
* Introduced a standardized content listings system for organizing
related guides and resources.
* Content listings now support both grid and list layouts for consistent
presentation.
* Added click telemetry for content listing interactions.
* **Documentation**
* Updated authentication, database, functions, getting started,
realtime, and storage guide pages to use the new content listing
components.
* Improved MDX structure examples and listing markup formatting in
contributor documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **New Features**
* Introduced a new content listings component for displaying guide
content in list and grid layouts across documentation pages.
* Added telemetry tracking for content listing interactions to measure
user engagement.
* **Documentation**
* Updated guide pages (Authentication, Database, Functions, Storage,
Realtime, Getting Started) to use the new listings layout.
* Added contribution guidelines for creating and managing content
listings in documentation.
* **Tests**
* Added comprehensive test coverage for content listings validation,
serialization, and rendering.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Nik Richers <nik@validmind.ai>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
## Summary
Since the guides UA-redirect shipped (GROWTH-811), named LLM bots
requesting `/docs/guides/*` get rewritten to the markdown handler, which
returns a 404 when no `.md` file exists. About 90K of those 404s per day
land on real pages that serve HTML 200 fine: the bot gets nothing on a
page that works.
The root cause is that the docs middleware hardcoded
`hasMarkdownVariant: true` for every guide path, so it never checked
whether a `.md` actually existed. I fixed it in two layers:
1. A build-time slug manifest makes `hasMarkdownVariant` truthful. Guide
pages with no `.md` now fall through to HTML 200 instead of a 404. This
is content-source-agnostic and future-proof: a new content source can
never silently regress to a 404.
2. A second generator pass emits real markdown for the troubleshooting
collection (the largest source, ~70% of the 404 volume), so those bots
get clean markdown rather than just HTML.
## Changes
- Add a shared `markdown-sources` module: a single source of truth for
which slugs get a `.md` (guides + troubleshooting), so the generator
output and the manifest cannot drift.
- Generate markdown for the troubleshooting collection (196 pages, TOML
frontmatter parsed via `smol-toml`), written under
`public/markdown/guides/troubleshooting/`.
- Emit a build-time slug manifest (a gitignored generated `.ts` module,
regenerated in `prebuild`, `predev`, and `pretypecheck`, mirroring the
existing `__generated__/graphql.ts` lifecycle).
- Gate the middleware's `hasMarkdownVariant` on the manifest: serve HTML
200 instead of a 404 for guide paths with no markdown variant.
This PR intentionally does not generate markdown for the ai-prompts,
YAML config, and externally-fetched (splinter) sources. The HTML
fallback covers them now; generating their markdown is follow-up work.
## Testing
Local verification (deterministic, against the real manifest and the
real negotiation function):
- Manifest invariant holds: 744 manifest slugs equal 744 generated `.md`
files.
- Generator emits 196 troubleshooting files with zero warnings,
frontmatter stripped, no leaked delimiters.
- Negotiation decision matrix, 6/6: covered slug + bot UA to markdown;
uncovered real page + bot UA to pass (HTML 200); nonexistent + bot UA to
pass; browser to HTML; covered + `.md` suffix to markdown; uncovered +
`.md` suffix to pass.
Verified on the Vercel preview deploy:
- [x] `User-Agent: ChatGPT-User` on a troubleshooting page returns `200
text/markdown` (real markdown body, frontmatter stripped).
- [x] `User-Agent: ChatGPT-User` on an uncovered real page
(`ai-tools/ai-prompts/code-format-sql`) returns `200 text/html` (was
404).
- [x] Browser request to the same uncovered page returns `200 text/html`
(unchanged for humans).
- [x] `User-Agent: ChatGPT-User` on a covered standard guide returns
`200 text/markdown` (no regression).
- [x] `User-Agent: ChatGPT-User` on a nonexistent guide URL returns
`404` (correct).
Known limitation: an explicit `.md`-suffix request on an uncovered page
still 404s by design (an explicit markdown request for a page that has
no markdown). The ~90K/day volume is plain-URL UA-based, so it is
unaffected.
Post-deploy, I will re-run the request-grain 404 reclassification in the
GROWTH-915 BQ workspace to confirm fixable guide markdown 404s drop to
near zero.
## Linear
- fixes GROWTH-946
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added generated markdown slug tracking for docs guides, improving
markdown availability detection.
* Added automated manifest generation and validation during docs build
and CI workflows.
* **Bug Fixes**
* Improved guide markdown negotiation so only supported guide slugs are
treated as having a markdown variant.
* Standardized markdown source handling for guides and troubleshooting
pages.
* **Tests**
* Added coverage for guide and troubleshooting slug generation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Reference documentation generation now only includes feature-enabled
SDK pages, so published docs better match what’s available.
* Legacy SDK reference pages are now shown selectively based on enabled
feature flags.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
In this PR:
- The `llms.ts` script is removed from the pipeline. It was just
iterating over the sections of the SDK JSON files to generate _dummy_
text files for LLMS to consume. But with a lot of inconsistencies and
mistakes.
- There's a new script that builds markdown files from the SDK
definition files.
- The Management API now has a definition file too, it was missing
before.
- On the www project now there are redirects for the reference text
files to the new markdown files in the docs project.
- NPM scripts have received better names so that prebuild ones are
smaller and all are easier to differentiate.
* Remove extra file.
* Remove unneeded tsconfig.jsons.
* Add @/* alias for importing in-package files to all apps.
* Remove baseUrl from all apps except studio (it'll require changes in almost all files).
* Fix baseUrl issues in docs, ui-library and design-system.
* Fix the typecheck for cms app. Fix all baseUrl errors in the cms app.
* Add deprecated flag to baseUrl in www.
Sitemap generation is failing when SDKs are disabled because it expects
to find generated files for the disabled SDKs. Fix by filtering to only
generate sitemap entries for enabled SDKs.
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
strictNullChecks was off for docs, which lets errors slip through and
leads to incorrect required/optional typing on Zod-inferred types. This
PR enables strictNullChecks and fixes all the existing violations.
* chore(docs,refs): prebuild self-hosted ref data
Pregenerate self-hosted ref data files, in the style of the client lib,
Management API, and CLI references. Preparatory step for migrating the
self-hosted references to App Router.
* refactor(docs): convert self-hosting to app router
Convert self-hosting reference pages to App Router.
* fix(docs,sitemap)
Pages were missing from the sitemap after the reorganization. Added them
back in.
Also added an optional priority that can be specified by including
`sitemapPriority` in content metadata. Used on the deprecated Auth
Helpers pages to see if we can tweak the relative SEO ranking for them.
