dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-05 17:35:10 +03:00
Code Issues Packages Projects Releases Wiki Activity
38,871 Commits 1,792 Branches 62 Tags
codex/fix-tanstack-e2e
Commit Graph
26 Commits
Author SHA1 Message Date
Miranda Limonczenko 36371de151 docs: trim CONTRIBUTING to repo mechanics and point at the style guide (#50743) 
Part 3 of 3. Stack: #50742 → #50744 → #50743. Review #50742 and #50744
first.

Closes DOCS-1177

## Problem

`CONTRIBUTING.md` mixed how to write a page with how the repo is laid
out. That's why it reached 568 lines, and why a contributor looking for
either half reads past the other.

#50742 gives the writing half its own home.

## Solution

Trim `CONTRIBUTING.md` to repo mechanics, 568 lines down to 163.

**Removed**, now in the style guide: general principles, information
types, document types, components and elements, styling and grammar,
word usage.

**Kept**: the skills table, repo organization, guide and reference
structure, content reuse, search. Content listings keeps its data file,
ID rules, and test command here; the when-to-use-one part is in the
style guide.

**Added**: a table linking each style guide file.

Wire the contributor-facing entry points at the guide:

- `apps/docs/AGENTS.md` — gains a style guide section listing each file
separately, so an agent can load one file without the others. This
auto-loads for anything under `apps/docs`, making it the
highest-leverage pointer in the repo.
- Root `AGENTS.md` — claimed the skills are "the source of truth for
conventions." For docs content style that's now the guide, with the
skills as the process that applies it.
- `.github/pull_request_template.md`, `.coderabbit.yaml`,
`apps/docs/README.md`, `apps/docs/DEVELOPERS.md` — updated paths.

Drop the `.prettierignore` exemption for `apps/docs/CONTRIBUTING.md`.
It's short enough to format now, and a repo that publishes a style guide
shouldn't exempt its own contributing doc.

## Notes for review

Discoverability in a markdown-only guide is entirely these pointers, so
they're the load-bearing part of this PR rather than cleanup.

Both surviving anchor links into `CONTRIBUTING.md` target
`#ai-agent-skills-for-docs-authoring`, which is kept. No dangling
anchors.

This PR sits last in the stack on purpose. It deletes the style sections
that seven skill instructions referenced, so it has to land after #50744
rewires them.

## Manual testing

1. Open `apps/docs/CONTRIBUTING.md` and confirm every remaining section
is repo mechanics, and the style guide table links resolve.
2. Confirm `apps/docs/AGENTS.md` names each style guide file, in size
order: `WORD_LIST`, `01-voice-and-tone`, `02-elements`,
`03-page-structure`.
3. Run `grep -rn "apps/docs/WORD_LIST" --include="*.md"
--include="*.yaml" . | grep -v node_modules` and confirm only the
intentional stub matches.
4. Run `npx prettier --config prettier.config.mjs --check
apps/docs/CONTRIBUTING.md`.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Updated contributor guidance to distinguish writing conventions from
repository mechanics, with the style guide as the reference for
documentation style.
* Added style guide links and clarified when to use the writing and
editing skills.
* Revised the docs contribution guide with a style guide file list and
steps for adding content listings.
* Updated the pull request checklist to direct contributors to the
documentation skills for style guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
 2026-09-25 20:22:47 -07:00
Miranda Limonczenko 7ce4ee53ae chore(docs) Retire supa-mdx-lint (#50602) 
Closes
[DOCS-1289](https://linear.app/supabase/issue/DOCS-1289/get-the-linter-to-fix-what-it-flags-or-retirereplace-the-linter)

Stacked on #50600, which points contributors at the authoring skills.
Merge that one first.

## Problem

Contributors experienced friction with the linter. They felt nickle and
dimed for tiny nits and felt detracted from the work itself. PRs would
become noisy with tiny one-word suggestions.

Additionally, our homegrown linter is not very intelligent, causing
frequent overrides.

## Solution

This removes the linter entirely in favor of directing contributors to
use SKILLS instead.

The removal entails...

- **CI.** Delete the three `docs_lint` workflows: the PR check, the
external-PR comment companion, and the nightly `--fix` bot. Drop the
stale `zizmor.yml` ignore entry for the deleted workflow.
- **Tooling.** Delete `supa-mdx-lint.config.toml` and the 14 rule files.
Drop the `lint:mdx` script and the `@supabase/supa-mdx-lint` dependency
from docs, learn, and ui-library, and regenerate the lockfile.
- **Content.** Remove the 181 directives. A separate commit carries
Prettier's reformatting of the tables and blank lines those comments had
suppressed, so the deletion commit stays readable. No prose changes.
- **Style guide.** The word list states each rule directly instead of
describing what the linter flagged. Every term survives, including the
phrase groups that mirrored `Rule004ExcludeWords`.
- **Skills.** `write-the-docs`, `edit-the-docs`, and `review-the-docs`
drop `pnpm lint:mdx` from their self-review commands and check the word
list directly. `ask-the-docs`'s CI reference drops both workflows.

## Manual testing

1. Run `git grep -i supa-mdx-lint -- . ':!pnpm-lock.yaml'`. No matches.
2. Run `pnpm install --frozen-lockfile --lockfile-only`. It passes, so
the lockfile matches the three trimmed manifests.
3. Run `git diff master...HEAD --name-only --diff-filter=ACMR | grep -E
'\.(md|mdx)$' | xargs npx prettier --config prettier.config.mjs
--check`. All changed markdown passes.
4. Open the [reformatted filter
table](https://docs-git-docs-retire-mdx-linter-supabase.vercel.app/docs/guides/observability/logs#filter-events)
on the preview and compare it with
[production](https://supabase.com/docs/guides/observability/logs#filter-events).
The table renders the same.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Documentation guidance now uses manual prose and terminology review
with the shared word list.
* Clarified storage configuration and common Realtime channel mistakes.
* Improved table formatting, text wrapping, and selected reference
links.
  * Updated documentation authoring and review guidance.

* **Chores**
* Retired automated MDX linting from workflows and local validation
commands.
* Removed lint-suppression markers throughout documentation without
changing instructions.
  * Added targeted documentation review guidance for pull requests.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
 2026-09-22 10:00:41 -07:00
Danny WhiteandJoshen Lim a31ca2bad0 fix(ui): make brand text readable across themes (#49871) 
## What kind of change does this PR introduce?

Bug fix and design-system update. Resolves DEPR-316.

Follow-up rename (`text-brand` → `text-primary`) is in a dedicated PR
(https://github.com/supabase/supabase/pull/50564) stacked on this one.

## What is the current behavior?

`text-brand` resolves to the canonical bright brand green in places that
need readable text, which fails WCAG AA on light surfaces. A separate
`text-brand-display` token adds another green for large type.

## What is the new behavior?

- `text-brand` maps to accessible `--primary` (light mode darkened to
meet ~4.5:1 AA)
- `--hue` / `--primary-hue` aligned to 157.5
- `text-brand-display` removed; former display callsites use
`text-brand`
- Bright fills/borders stay on `brand-default`
- Design-system colour and typography docs updated

| Before | After |
| --- | --- |
| <img width="514" height="112" alt="CleanShot 2026-09-02 at 11 13
09@2x"
src="https://github.com/user-attachments/assets/4e0138a9-a32d-4e4c-a426-90736706e1e7"
/> | <img width="512" height="138" alt="CleanShot 2026-09-21 at 11 42
05@2x"
src="https://github.com/user-attachments/assets/164cc5b1-a0c5-4e93-95f1-80016641a114"
/> |
| <img width="864" height="266" alt="CleanShot 2026-09-02 at 11 13
53@2x"
src="https://github.com/user-attachments/assets/3c1ca53f-bf9e-431e-bc15-816b4a275b8e"
/> | <img width="882" height="248" alt="CleanShot 2026-09-21 at 11 41
37@2x"
src="https://github.com/user-attachments/assets/24828e7b-ed6b-44cb-b9dc-becc3398bdfc"
/> |
| <img width="782" height="692" alt="CleanShot 2026-09-02 at 11 16
30@2x"
src="https://github.com/user-attachments/assets/fc871977-77bc-47fb-9e0e-9284e0ecd5cc"
/> | <img width="730" height="690" alt="CleanShot 2026-09-21 at 11 42
52@2x"
src="https://github.com/user-attachments/assets/bf479515-d5f9-471e-b82d-f097c0f4b56c"
/> |
| <img width="480" height="306" alt="CleanShot 2026-09-02 at 11 18
53@2x"
src="https://github.com/user-attachments/assets/03f341f4-f02e-44f8-a2b2-8c31670d0427"
/> | <img width="470" height="300" alt="CleanShot 2026-09-21 at 11 43
19@2x"
src="https://github.com/user-attachments/assets/9df18217-d5e6-48b8-ba0b-579d2664b94b"
/> |
| <img width="960" height="300" alt="CleanShot 2026-09-02 at 11 32
04@2x"
src="https://github.com/user-attachments/assets/6b1d9373-7a71-4247-81ff-26441604b09d"
/> | <img width="980" height="306" alt="CleanShot 2026-09-21 at 11 44
13@2x"
src="https://github.com/user-attachments/assets/41ad4784-02ec-4b29-b860-32af9fa79aa8"
/> |
| <img width="924" height="214" alt="CleanShot 2026-09-02 at 11 34
44@2x"
src="https://github.com/user-attachments/assets/1de661fe-c7b6-499b-a94f-e4737436ec79"
/> | <img width="752" height="162" alt="CleanShot 2026-09-21 at 11 44
56@2x"
src="https://github.com/user-attachments/assets/1811890f-0660-4445-84e9-447720954fa1"
/> |

## To test

Test each callsite **in light mode** (dark mode is largely unchanged).

### WWW

-
[Homepage](https://zone-www-dot-com-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/):
“Scale to millions” uses readable brand text (display token is gone)
-
[Careers](https://zone-www-dot-com-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/careers):
small “Careers” eyebrow readable; green dividers stay bright
`brand-default`
-
[Contact](https://zone-www-dot-com-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/contact-us):
email / policy links use readable brand text
-
[Regions](https://zone-www-dot-com-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/regions):
“Ask about early access to BYOC” readable

### Docs

- [Docs
homepage](https://docs-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/docs):
“DOCS” wordmark and resource links readable
- [Database
overview](https://docs-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/docs/guides/database/overview):
nav / footer brand links readable
- [JavaScript
reference](https://docs-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/docs/reference/javascript/introduction):
active sidebar treatment readable

### Design system

-
[Typography](https://design-system-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/docs/typography):
documents `text-brand` only (no display)
- [Colour
usage](https://design-system-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/docs/color-usage):
`text-brand` vs `bg-brand-default`
- [Design-system
homepage](https://design-system-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/):
brand text examples across themes

### Studio

- [Auth
providers](https://studio-staging-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/dashboard/project/_/auth/providers):
enabled provider badge text readable; status dot stays bright
- [Database
policies](https://studio-staging-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/dashboard/project/_/database/policies?new=true):
template hover text more legible
- [Database
connections](https://studio-staging-git-dnywh-depr-316-brand-text-tokens-supabase.vercel.app/dashboard/project/_/observability/connections):
“Live” status readable; animated dot stays bright green

---------

Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
 2026-09-22 10:07:28 +10:00
Miranda Limonczenko 1608b16687 chore(docs) Direct contributors to the docs authoring skills (#50600) 
Prerequisite for
[DOCS-1289](https://linear.app/supabase/issue/DOCS-1289/get-the-linter-to-fix-what-it-flags-or-retirereplace-the-linter).

## Problem

The `write-the-docs` and `edit-the-docs` skills carry the docs style
guide, so a contributor who uses them writes to the guide without having
read it. Right now nothing points a contributor at them.
`apps/docs/CONTRIBUTING.md` describes the skills as an option for agent
users, halfway down a 559-line page, and no other contributor-facing
file mentions them at all.

## Solution

- **CodeRabbit reminder.** One path instruction for
`apps/docs/content/**/*.mdx`. When a page collects two or more style,
terminology, or structure issues, CodeRabbit adds a single comment
pointing the author at `/write-the-docs` or `/edit-the-docs`. A single
nit gets no pointer, so the comment reads as a signal rather than
boilerplate.
- **Docs CONTRIBUTING.** The intro lists the skills by task, draft
through self-review, before the style rules, and links the existing
skills section for framing and architecture. The section opener now
reads as an expectation rather than a conditional, with the agent
mechanics moved to a second paragraph.
- **Root CONTRIBUTING.** A pre-flight check under Pull Requests, with
the same task list nested under it. Matches the docs checklist item in
#50591.
- **Word list.** Names the skills that apply the list.
- **Docs README and DEVELOPERS.** One sentence in each Contributing
section.

**Not in this PR:** CodeRabbit reminds, it doesn't enforce. Feeding the
two `SKILL.md` files to `knowledge_base.code_guidelines` would make it
review docs content against the style guide. That's a decision for
DOCS-1289 itself.

**Verification caveat:** this PR changes no MDX under
`apps/docs/content/`, so the new path instruction doesn't fire on its
own review.

## Manual testing

1. See all new content references in the diff.
2. Review for clarity and value.
3. Consider suggesting other ways to promote the usage of this skill to
all docs contributors.
 2026-09-21 10:07:21 -07:00
Miranda Limonczenko 3e6b40b238 chore(docs): revise CONTRIBUTING for common pitfalls with Information types (#50357) 
## Problem

Our CONTRIBUTING and WORD_LIST is doing a pretty good job at improving
contributor documentation, but I consistently see some issues:
- **Uses "This guide":** "This guide..." is no longer recommended based
on discussions with Nik. Instead, recommendation is to omit those words
while still including a value statement. I still do not recommend
including a definition of the title term as an opening sentence.
- **Mixed information types:** I still often see mixed information types
or wordy, chunky paragraphs. Without a definition in place, my agent
mistakenly thought there was just "Procedure, Context, and Reference."

## Solution

- **A new Information types section** that clearly outlines definitions
and usage with cross-references so that this guidance is not easily
missed.
- **Removed "This guide"** recommendation in favor of a value statement.

Additionally added a clear rule about how to spell numbers consistently
and gave more guidance about how to structure a large topic.

## Manual testing

1. Open
[apps/docs/CONTRIBUTING.md](https://github.com/supabase/supabase/blob/docs/value-statements-and-counts/apps/docs/CONTRIBUTING.md)
on this branch. The Information types section renders its table, the
Recommendations list, and both fenced examples.
2. Click the two `Information types` links, one in General principles
and one under Guides. Both jump to the section.
3. Open
[apps/docs/WORD_LIST.md](https://github.com/supabase/supabase/blob/docs/value-statements-and-counts/apps/docs/WORD_LIST.md).
The `numbers` entry sits under N, ahead of `numbers in product
versions`.
4. Run `npx prettier --check apps/docs/CONTRIBUTING.md
apps/docs/WORD_LIST.md` from the repo root. It reports no formatting
changes.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Expanded the contribution guide with Information Mapping guidance for
procedures, processes, principles, concepts, structures, and facts.
- Clarified paragraph and section grouping, page-level classification,
recommended ordering, navigation, transitions, outcomes, and connective
prose.
- Added guidance to use value-focused introductions and bold
“Recommended” and “Not recommended” labels.
- Added number-formatting guidance, including numeral usage, ranges,
fractions, and when to omit step or item counts.
  - Updated related entries in the documentation word list.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
 2026-09-16 11:40:19 -07:00
Nik RichersandNik Richers ea79df46bc docs: explain purpose of /edit-the-docs in CONTRIBUTING.md rather than the "Write the docs" checklist (#50313) 
## 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 authoring guidance: keep `/edit-the-docs` out of the Write the docs
checklist and document when to use what skill in `CONTRIBUTING.md`.

## What is the current behavior?

The Write the docs checklist mentions `/edit-the-docs` mid-flow and
lists it among checklist skills. That skill is a different workflow and
audience, so it risks steering people off the six-stage process.

## What is the new behavior?

- Checklist lists only Write the docs skills; no `/edit-the-docs`
mid-stage note.
- `CONTRIBUTING.md` splits **Write the docs skills** from **Edit
existing pages**.
- Write the docs applies when product intent and code drive the change,
including revising or restructuring existing pages. `edit-the-docs` is
for style, structure, or brevity when the product story is unchanged.

## Additional context

Also drops a redundant `/test-the-docs` note from "What good looks like"
(Self-review still covers it).

---------

Co-authored-by: Nik Richers <nik@validmind.ai>
 2026-09-14 09:02:17 -07:00
Miranda LimonczenkoandClaude Opus 5 c7534b9e29 docs: document the stacked PRs workflow in edit-the-docs (#50018) 
Closes DOCS-1381

## Problem

The `edit-the-docs` skill describes a page edit as one continuous pass
and has no notion of output. No commits, no branches, no PRs. It ends at
edited files in the working tree.

That leaves a reviewer one diff that mixes reworded prose, moved
sections, and corrected claims, where a move can't be told from a
rewrite.

## Solution

- **Split the edit by change type:** style, structure, technical
revision, and additions. Style runs before structure, so the structure
diff reads as pure moves against already-clean prose.
- **Ship one PR, one change type per commit.** A stack of PRs is an ask,
not a default. When the edit both rewrites prose and moves sections and
runs over roughly 150 changed lines, the skill says how large the diff
is and offers the split. The requester decides, and no answer means one
PR. A stack buys clean per-type diffs, and it costs a reviewer the
whole-edit view, since no PR page shows it.
- **State the scope boundary once.** The edit is exactly the buckets
that have content. A dropped bucket is beyond the edit, and a later
request for that change type is a new request. Additions stay
author-driven, which keeps a mid-edit request from reopening an earlier
commit.
- **Scope the technical pass with a wrong-outcome test.** A claim
changes only when leaving it would hand the reader an error, a different
result than the page promises, or a fact that isn't true. An external
best-practices rule doesn't clear that gate on its own, and a missing
safeguard is an absence, so it goes to additions. Without the test, a
verification pass becomes a rewrite.
- **Add `reference/stacked-prs.md`** for the `gh stack` commands, branch
naming, restack auditing, and the one command that diffs a whole stack
at once.

### What driving the skill on a real page changed

Running it end to end on a 684-line guide, then shipping the result,
corrected five things a read-through didn't:

- **The anchor gate grepped the wrong scope.** It said
`apps/docs/content`. Five of the seven inbound anchors to that page
lived outside it, in Studio components and `apps/www`, and those are the
matches that break a Docs button in the product. The gate is now
repo-wide and is step 1 of the structure pass, because moving a section
preserves its slug and only renaming breaks it. That's what makes an
aggressive regroup safe.
- **Grouping sections by subject doesn't work.** On a page about tables
every section is about tables, so subject grouping produces one
task-named bucket that collects the background too. Classification is
now by what the reader is doing, and the skill carries the outline that
page settled on.
- **Snippet testing finds claims, it doesn't just confirm them.** One
example re-created a table an earlier example had made, which stopped
that block and left a third example referencing a table nothing ever
created. Every fence was individually correct; the sequence was not. So
the rule is to run every fence in document order, because that order is
what the reader pastes.
- **Restacking silently drops upper-branch edits.** The conflict
presents as new structure versus old content being re-added, and
resolving toward the structure takes the edit with it. `stacked-prs.md`
says to audit each branch with a grep per expected change rather than
reading the diff.
- **`build:guides-markdown` dirties a tracked file.** It writes
`apps/docs/public/markdown/manifest.json`, which the repo commits as
`[]`. Without a note the artifact lands in the next commit.

## Manual testing

1. Open `.agents/skills/edit-the-docs/SKILL.md` and read Phase 0. You
can tell whether to ship one PR or offer a stack, and what to say when
offering it, without opening the reference file.
2. Read the PR 3 section. The wrong-outcome test, the external-rule
tiebreaker, and the absences line together tell you where a
best-practices violation goes.
3. Run `npx prettier --check .agents/skills/edit-the-docs
apps/docs/CONTRIBUTING.md`. Reports all matched files use Prettier code
style.
4. Run `cat .claude/skills/edit-the-docs/reference/stacked-prs.md`. The
branch table resolves through the `.claude/skills` symlink and shows
`4+` as a pattern.
5. Run `git diff master -- .agents/skills/write-the-docs/SKILL.md`.
Reports no changes, so nothing in `write-the-docs` routes a drafter into
this workflow.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Updated guidance for editing existing documentation through distinct
style, structure, technical, and additions phases.
- Added work-sizing, scope, validation, confirmation, and handoff rules
for stacked pull requests.
- Documented support for multiple topic-based additions branches and
their merge order.
- Clarified when to use drafting versus editing workflows, including
when a draft becomes a restructure.
- Improved guidance for validating code examples, checking
repository-wide references, handling generated artifacts, and updating
pull request titles.
  - Updated contributor guidance and related documentation references.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
 2026-09-11 14:26:34 -07:00
Nik RichersandNik Richers 0322720743 docs: add test-the-docs skill and pm-the-docs universe lookup (#49913) 
## I have read the CONTRIBUTING.md file.

YES

## What kind of change does this PR introduce?

Docs authoring skills / contributor enablement.

## What is the current behavior?

- The "Write the docs" bar asks for runnable examples, but skills stop
at lint/build (`/review-the-docs`) and do not execute inline MDX
snippets.
- Cross-repo product grounding depends on a single-repo read; there is
no skill guidance for `supabase/universe` when you have Supabase org
access.

## What is the new behavior?

- Adds `/test-the-docs` to run procedural snippets against a
Docker-isolated local stack (`supabase start` in a temp project), with
Verification table output.
- Teaches `/pm-the-docs` cross-repo product lookup
(`reference/universe-lookup.md`) with a capability gate: universe when
you have Supabase org access (or a local clone), otherwise a first-class
OSS public-search path. `ask-the-docs` stays docs-app only.
- Updates the checklist mirror, CONTRIBUTING skills table, and light
handoffs in `write-the-docs` / `review-the-docs`.

## Additional context

Vault "Write the docs" checklist updated separately; Linear document
needs a Claude-side delta sync after merge.

### Test plan

- [ ] Symlinks: `.claude/skills` is a Git symlink to
`../.agents/skills`; `.claude/skills/test-the-docs/SKILL.md` resolves
- [ ] No hardcoded personal absolute paths under `.agents/skills/`
- [ ] CONTRIBUTING lists skills including `/test-the-docs`
- [ ] `/pm-the-docs` references `universe-lookup.md` capability gate;
`/ask-the-docs` Related points there for product lookup
- [ ] OSS path: no universe clone / submodule init when `gh api
repos/supabase/universe` fails
- [ ] Docker up: dry-run `/test-the-docs` against one MDX page with
SQL/CLI (optional smoke)
- [ ] Docker down: skill documents graceful `deferred` (not silent skip)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Added documentation guidance for testing runnable examples in an
isolated local environment.
- Added cross-repository product lookup guidance, including capability
checks and source tracking.
- Added verification report templates with standardized results and
environment details.

- **Documentation**
  - Expanded authoring, review, self-review, and contribution guidance.
- Improved safety instructions for local snippet testing, including
credential protection and cleanup.
- Updated repository layout, tooling, links, and workflow references for
documentation skills.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Nik Richers <nik@validmind.ai>
 2026-09-04 00:34:45 +00:00
Alaister YoungandAlaister Young f125126aec chore: make agent instructions agent-agnostic (#49941) 
Makes the repo's AI-agent setup tool-agnostic: instructions live in
`AGENTS.md` files, skills live in `.agents/skills/`, and Claude Code,
Codex, Cursor, and Copilot all read the same sources. Also sweeps the
skills for stale and duplicated content while everything was being
moved.

**Changed:**
- Every `CLAUDE.md` (root, `apps/studio`, `apps/docs`, `apps/kb`) is now
a one-line `@AGENTS.md` import; the content moved verbatim into an
`AGENTS.md` beside it. The root one moved from `.claude/CLAUDE.md` to
the repo root for consistency.
- All skills now live in `.agents/skills/`; `.claude/skills` is a single
symlink to it (replacing the old mix of real dirs and per-skill
symlinks). Path references in `.coderabbit.yaml`, code comments, and
docs updated to match.
- `.github/copilot-instructions.md` keeps only the review policy and
points at `AGENTS.md` + `.agents/skills/`. Copilot code review reads
those natively now, so the per-topic
`.github/instructions/*.instructions.md` files were duplicates of the
skills.
- Stale skill content fixed: `studio-queries` imported a toast library
Studio doesn't use, `telemetry-standards` and `studio-testing` used
import paths that don't resolve, `safe-sql-execution` cited a boundary
test that doesn't exist, the ask-the-docs references described an
`AiPrompt` mechanism that was replaced by the ID-keyed registry, plus a
handful of wrong paths, a self-contradicting `waitForTimeout` rule, an
invalid Playwright signature, and a ConfigCat flag described as PostHog.
- `studio-error-handling` now explains when to use `AlertError` (the
default) vs `ErrorMatcher`.

**Added:**
- `apps/docs/AGENTS.md` (docs test requirements, from the old Cursor
rule)
- `studio-shortcuts` skill (from the old Copilot instruction file,
verified against the current registry)
- `ask-the-docs/reference/graphql-endpoint.md` and
`search-embeddings.md` (from the old Cursor rules, with the missing
resolver/registration/codegen steps filled in)
- Feature-flag measurement section in `telemetry-standards`

**Removed:**
- `.cursor/` (rules folded in as above; skill symlinks no longer needed)
and `.cursorignore`
- `.github/instructions/` (8 files)
- `vercel-composition-patterns/AGENTS.md` – a 946-line verbatim
concatenation of its own `rules/` directory, and a nested `AGENTS.md`
that agents could auto-load as repo instructions
- `edit-the-docs/reference/structure-and-flow.md` – word-for-word copy
of the skill's own Phase 2 text

## To test

- `readlink .claude/skills` → `../.agents/skills`, and `ls
.claude/skills/copywriting/SKILL.md` resolves
- Open a Claude Code session at the repo root and in `apps/studio` – the
imported `AGENTS.md` content should load as before
- `git diff master --stat -M` shows the skill moves as 100% renames
(content unchanged except the listed fixes)
- Spot-check a fixed claim, e.g. `import { toast } from 'sonner'` in
`studio-queries`, or the `logs.all` ESLint rule cited in
`clickhouse-logs-queries/references/codebase-integration.md`

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Expanded guidance for documentation workflows, GraphQL resources,
search, ClickHouse logs, React forms, Studio testing, shortcuts,
telemetry, accessibility, copywriting, and composition patterns.
- Clarified local testing, linting, build workflows, error handling, and
AI coding agent usage.
- Added contributor guidance for the knowledge base, documentation, and
Studio areas.

- **Chores**
  - Consolidated agent instructions and skill references.
- Removed obsolete editor-specific guidance, duplicate links, and
superseded documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
 2026-09-03 21:58:29 +08:00
Nik RichersCursor AgentNik RichersMiranda Limonczenko
 		a27f81d5a0 docs: improve write-the-docs skill and retire docs-content (#49089) 
## I have read the CONTRIBUTING.md file.

YES

## What kind of change does this PR introduce?

Improves the `write-the-docs` skill and retires the overlapping
`docs-content` skill (provided @czenko agrees to the latter).

## What is the current behavior?

- Docs drafts could leak future-tense / internal roadmap language, add
redundant verbiage, and add single-item lists.
- No explicit CONTRIBUTING.md / WORD_LIST.md compliance pass for docs
drafts.
- Product intent was assumed to come from Linear without a good path
path for open-source contributors.
- `docs-content` overlapped `write-the-docs` and the broader
`*-the-docs` skill set (e.g. I started
[#49432](https://github.com/supabase/supabase/pull/49432) before
realizing we should likely not have overlapping skills).

## What is the new behavior?

- Codifies draft pitfalls as principles in
`reference/common-pitfalls.md` (timelessness, strip internal business
context, redundancy, single-item lists), with style detail pointed from
`SKILL.md` rather than duplicated.
- Clarifies SoT: Linear + code inspection for content accuracy;
CONTRIBUTING.md / WORD_LIST.md (and future DOCS-1177 style guide) for
voice/terminology/formatting only. `common-pitfalls.md` is flagged to
fold into that guide later.
- Linear is internal and preferred when available, not required for
open-source. Missing product intent: stop Draft and hand off to
`pm-the-docs` (Frame) / `ask-the-docs` (Shape/IA); do not invent
positioning or run Frame/Shape inside this skill.
- Adds drafting mechanics notes, a compliance checklist before handoff,
and a local `/review-the-docs` self-review step.
- Removes `.claude/skills/docs-content/`; `.claude/CLAUDE.md` points at
the canonical docs skills. Supersedes #49432.

## Additional context

Based on @czenko review feedback on #49020 and feedback I received for
`docs-content` from @aantti while trialing the "Write the docs" process
with contributors, plus my own testing while drafting docs for product
managers.

### Test plan

- [ ] `SKILL.md` reads as Draft-only; Frame/Shape stay with
`pm-the-docs` / `ask-the-docs`
- [ ] No-Linear path: ask for Linear (internal) or hand off Frame/Shape;
no invented positioning
- [ ] `.claude/skills/docs-content/` gone; `.claude/CLAUDE.md` updated
- [ ] `.claude/skills/write-the-docs` symlink still resolves to
`.agents/skills/write-the-docs`
- [ ] Next `/write-the-docs` run: compliance re-read + pitfalls guidance
before handoff

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Added an `edit-the-docs` workflow for restructuring and improving
existing documentation pages.
- Expanded authoring guidance for concise, timeless, user-focused
content grounded in product intent.
- Added references covering common writing pitfalls, link and anchor
conventions, and validation workflows.
- Clarified that style guidance applies to voice, formatting, and
terminology—not product behavior.
- Updated documentation workflows to distinguish planning, writing,
editing, review, and assistance responsibilities.
- Replaced the previous standalone docs-content skill with the updated
authoring skill model.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Nik Richers <nik@validmind.ai>
Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io>
 2026-09-02 18:48:59 +00:00
Danny White 34454037d3 clean up docs admonition structure (#48669) 
## What kind of change does this PR introduce?

Docs update. Resolves DEPR-634.

Stacked on #48664. The linter package and CI revision pins will be
updated after
[supa-mdx-lint#121](https://github.com/supabase-community/supa-mdx-lint/pull/121)
merges and is released.

## What is the current behavior?

Admonition body content can contain structural headings, which inherit
prose spacing and produce awkward callout layouts. Standalone Docs
actions are also rendered as ordinary body content in two places.

| Before |
| --- |
| <img width="1264" height="840" alt="70168"
src="https://github.com/user-attachments/assets/00aa7620-a6b4-452c-971f-b3ce2eda0e8c"
/> |
| _Recent violation with Markdown header in `children`. Notice the big
gap up top._ |

## What is the new behavior?

- Documents that admonition titles belong in the `title` prop,
standalone calls to action belong in `actions`, and document sections
belong outside admonitions.
- Configures heading-inside-admonition violations as errors for the
forthcoming linter release.
- Moves the UI-library and wrapper dashboard buttons into the existing
`actions` slot without changing the shared component.

Validated with the forthcoming linter across all 810 Docs sources, Docs
type-checking, targeted ESLint and Prettier checks, and desktop/mobile
rendering.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Clarified admonition guidelines for optional titles, headings, rich
content, and standalone calls to action.
* Improved guidance on when contextual links and interactive examples
belong in admonition content.

* **Style**
* Updated documentation call-to-action buttons to use the designated
actions area.

* **Quality Improvements**
* Added validation to prevent headings inside admonitions and maintain
consistent formatting.
  * Updated documentation linting to apply the latest validation rules.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
 2026-08-24 00:26:03 +00:00
Nik RichersandNik Richers cf36ad9e52 feat(skills): move Write the docs skills into the monorepo — DO NOT REVIEW YET (#48914) 
## I have read the CONTRIBUTING.md file.

YES

## What kind of change does this PR introduce?

Adds four AI agent skills that support docs contributors across the
authoring lifecycle, intended to lower the barrier to entry for
contributing to our docs.

Closes DOCS-1287.

## What is the current behavior?

Our process for writing docs is somewhat undefined beyond some general
guidance in CONTRIBUTING.md and we don't make as easy to contribute to
our docs as we could. As a result, content often needs additional
changes during PR reviews or requires further revisions after merging.

The four AI agent skills in this PR already existed in a private repo
where I've been testing them but they were not previously available for
general use until now.

## What is the new behavior?

- Four skills added under `.agents/skills/`, symlinked from
`.claude/skills/` and `.cursor/skills/` (same pattern as the existing
`vitest` skill).
- `ask-the-docs`: answers architecture and design questions about
apps/docs (MDX pipeline, content components, federated docs) and checks
whether a proposed change fits existing docs app patterns.
- `write-the-docs`: drafts net-new or substantially rewritten docs
content for a feature or launch, grounded in the Linear ticket, the
actual code, and the docs style guide.
- `review-the-docs`: runs a local, PR-type-specific review checklist
against any open supabase/supabase docs PR (markdown pipeline, MDX
content, tutorials, examples, Studio links) and produces a consolidated
report.
- `pm-the-docs`: supports "Write the docs" authoring process across the
different phases.
- `apps/docs/CONTRIBUTING.md` gets a new "AI agent skills for docs
authoring" section mapping each skill to its checklist stage
- Cross-references to skills that stay in `docs-agent-skills`
(`work-linear-issue`, `audit-docs-ia`, `create-pull-request`,
`proof-it-works`, `pm-the-docs-full`) now point there via absolute
GitHub links instead of relative paths

## Additional context

- Companion PR:
[supabase/docs-agent-skills#28](https://github.com/supabase/docs-agent-skills/pull/28).
Removes the three moved skills, renames `pm-the-docs` to
`pm-the-docs-full`, and fixes now-dangling inbound links.
- Worktree:
`~/GitHub/supabase/supabase-worktrees/nikrichers/docs-1287-move-skills-mentioned-in-write-the-docs-from-docs-agent`
- Opened as draft: this is a docs-authoring-tooling change with no
runtime/build surface. Flip to ready once you've sanity-checked the
skill content.

### Test plan

- [ ] `ls -la
.claude/skills/{ask-the-docs,pm-the-docs,write-the-docs,review-the-docs}`
resolves to `.agents/skills/...`
- [ ] Open a fresh Claude Code session with cwd in this repo and confirm
`/ask-the-docs`, `/pm-the-docs`, `/write-the-docs`, `/review-the-docs`
are available
- [ ] Read the new section in
[`apps/docs/CONTRIBUTING.md`](apps/docs/CONTRIBUTING.md) in context
- [ ] Spot-check
`.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md` has
no `linear.app` links and carries the snapshot disclaimer

---------

Co-authored-by: Nik Richers <nik@validmind.ai>
 2026-08-12 22:48:30 +00:00
Danny White c0f1ef51fb feat(docs): migrate resources and getting-started to ContentListings (#48517) 
## 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 -->
 2026-08-03 00:52:44 +00:00
Miranda Limonczenko 0d465e7b5f chore(ui): Remove 'tip' from Admonition (#48419) 
Closes FE-3966

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## Problem

- The admonition uses both 'tip' and 'note', but the visual distinction
has long-ago collapsed.
- 'Note' is used far more frequently than 'tip'
- The two are very similar and it is confusing to know which one to use
when they are visually identical

## Solution

Collapse 'tip' and 'note' into one by removing all places where there is
'tip' and updating all references to 'tip' into 'note'.

**Note:** This PR also resolves new broken links flagged by the E2E docs
checker. It may move to another PR since E2Es keep erroring.

### Specific changes

See below for an AI-generated list of changes:

- **Type system** — removed `'tip'` from `AdmonitionType`, its
`TYPE_TO_VARIANT`/`TYPE_LABEL` entries, and the test case in
[`packages/ui-patterns/src/Admonition/](packages/ui-patterns/src/Admonition/)
- **Remark plugin** —
[remarkAdmonition.ts](apps/docs/lib/mdx/plugins/remarkAdmonition.ts) now
maps mkdocs `tip` → `note`
- **Lint allowlist** — `tip` dropped from `supa-mdx-lint.config.toml`
- **Content migration** — all 109 files with `type="tip"` (across
`apps/docs`, `apps/www`, `apps/studio`) converted to `type="note"`; zero
remaining hits confirmed by repo-wide grep
- **Style guide** — `CONTRIBUTING.md` and `contributing/content.mdx`
updated to describe 4 admonition types instead of 5

### Usage before implementation

See the usage table that points toward 'note' as being dominant across
all apps:

Here's the usage table:

| Location | `note` | `tip` |
|---|---|---|
| apps/docs | ~480 | ~143 |
| apps/studio | 34 | 6 |
| apps/www (blog) | 19 | 3 |
| packages/ui-patterns (tests) | 3 | 1 (parametrized) |
| design-system / ui-library / packages/ui / packages/common | 0–1 (test
fixture only) | 0 |

## Preview links


| App | Page | Search text (Ctrl+F) | Verify |
|---|---|---|---|
| docs |
[/docs/guides/ai-tools/byo-mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/byo-mcp)
| official MCP TypeScript SDK | callout's aria-label="Note" |
| docs |
[/docs/guides/ai-tools/mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/mcp)
| MCP server is available at | callout's aria-label="Note" |
| docs |
[/docs/guides/ai/python-clients](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai/python-clients)
| Click Connect at the top of any project page | callout's
aria-label="Note" |
| docs |
[/docs/guides/auth/audit-logs](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/auth/audit-logs)
| Disabling Postgres storage reduces your database storage costs |
callout's aria-label="Note" |
| docs |
[/docs/guides/database/tables](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/database/tables)
| access a custom schema through the Supabase Data API | callout's
aria-label="Note" |
| docs |
[/docs/guides/troubleshooting/edge-function-404-error-response](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/troubleshooting/edge-function-404-error-response)
| Always configure an appropriate time frame | callout's
aria-label="Note" (was single-quoted type='tip') |
| www | [blog:
cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code)
| Detecting config drift | callout's aria-label="Note" |
| www | [blog:
cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code)
| Setting Edge Function secrets | callout's aria-label="Note" |
| www | [blog:
nosql-mongodb-compatibility-with-ferretdb-and-flydotio](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/nosql-mongodb-compatibility-with-ferretdb-and-flydotio)
| If your network supports IPv6 connections | callout's
aria-label="Note" |

Note: the `www` rows use the `zone-www-dot-com` preview host, not the
`docs` one you gave — since blog pages are served from the www app, not
docs.


## Manual testing

1. Open preview links for affected pages.
2. Inspect. Open console.
3. Paste the following in and see there is no 'Tip' on the page:
```
document.querySelectorAll('[role="alert"]').forEach(el => console.log(el.getAttribute('aria-label'), el.textContent.slice(0,60)))
```



<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Standardized informational callouts across docs and tutorials from
**“Tip”** to **“Note”**, updating multiple examples and guidance blocks.
* Updated a few related doc references/links and conditional “Next
steps” content.
* **UI Updates**
* Switched various in-app banners and notices to the **“Note”** style
variant.
* **Bug Fixes / Improvements**
* Removed support for the retired **“Tip”** callout type and aligned
docs linting, component behavior, and aria labeling to the remaining
admonition types.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
 2026-07-29 09:26:50 -07:00
Miranda Limonczenko c1d010a699 feat(docs) Add a SKILL to write stronger documentation and apply it to guides/api/securing-your-api (#48018) 
Closes DOCS-1176

## Summary

This PR adds documentation-writing guidance for humans and agents, then
applies it to the “Securing your API” guide.

## Changes

- Add a documentation word list based on Google’s style guide and
existing MDX lint rules.
- Add a shared `docs-guides` Agent Skill with Cursor and Claude
integration.
- Expand contributing guidance for information types, procedures,
chunking, links, admonitions, grammar, and terminology.
- Restructure “Securing your API” into contextual and procedural
sections.
- Add section navigation, cross-references, transitions, and procedural
outcomes.
- Reduce repeated admonitions and improve scannability.

## Manual testing

1. Open `/docs/guides/api/securing-your-api` in Preview and compare to
Live.
https://docs-git-docs-restructure-api-supabase.vercel.app/docs/guides/api/securing-your-api
2. See that the content is improved and clear with no important context
removed.
3. See the Admonitions that are no longer marked as admonitions. See the
content still makes sense.
4. Review the diff of `CONTRIBUTING.md` and `WORD_LIST.md`.
5. See that you agree with the new rules and that they are clear.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Updated documentation-writing guidelines with clearer standards for
structure, formatting, components, diagrams, terminology, and
navigation.
* Added a comprehensive word and style reference for consistent
documentation language.
* Reworked the API security guide with clearer guidance on grants, RLS,
dedicated schemas, pre-request checks, rate limiting, and API keys.
* Added documentation authoring workflow guidance, including validation
and formatting steps.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
 2026-07-17 18:48:45 +00:00
Nik RichersNik RichersJeremias Menichelli
 		635b2d6050 docs: standardise next steps on overview pages with content listings (#47097) 
## 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)
|
|
---------------------------------------------------------------------------------------------------------------------------
|
---------------------------------------------------------------------------------------------------------------------------
|
| ![Auth
before](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/auth-before-dbc93ccd.png)
| ![Auth
after](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/auth-after-789b25a6.png)
|

#### 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)
|
|
--------------------------------------------------------------------------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------------------------------------------------------------------------
|
| ![Database
before](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/database-before-0d32136a.png)
| ![Database
after](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/database-after-22447d16.png)
|

#### 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)
|
|
--------------------------------------------------------------------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------------------------------------------------------------------
|
| ![Functions
before](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/functions-before-11319580.png)
| ![Functions
after](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/functions-after-83268362.png)
|

#### 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)
|
|
----------------------------------------------------------------------------------------------------------------------------------------
|
----------------------------------------------------------------------------------------------------------------------------------------
|
| ![Storage
before](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/storage-before-9b4ae535.png)
| ![Storage
after](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/storage-after-7503d664.png)
|

#### 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)
|
|
-------------------------------------------------------------------------------------------------------------------------------------------
|
-------------------------------------------------------------------------------------------------------------------------------------------
|
| ![Realtime
before](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/realtime-before-6eb5b125.png)
| ![Realtime
after](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/realtime-after-92ec7d74.png)
|

#### 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)
|
|
------------------------------------------------------------------------------------------------------------------------------------------------------
|
------------------------------------------------------------------------------------------------------------------------------------------------------
|
| ![Getting Started
before](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/getting-started-before-89251d7b.png)
| ![Getting Started
after](https://moijyfpvgnmgoxvwcikq.supabase.co/storage/v1/object/public/pr-proof/supabase/supabase/pr47097/getting-started-after-3e33c6d4.png)
|

### 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>
 2026-06-29 23:57:12 +00:00
Miranda LimonczenkoandMiranda Limonczenko dcf02db5c7 chore(docs) Prescribe more detailed docs style lints (#46895) 
Closes
[DOCS-1036](https://linear.app/supabase/issue/DOCS-1036/add-docs-lint-rule-for-copywriting-style-gaps)

## 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?

This change expands upon the "us this, not that" style rules and applies
them to our linting.

## What is the current behavior?

Our current behavior does far fewer checks.

## What is the new behavior?

The new behavior spots the following:

- Suggesting swapping Latin phrases for common English
- Remove formal words for simpler words
- Removes marketing language
- And more (see code diff)

## Additional context

For more information about general style rules, see the style guide:
https://supabase.com/design-system/docs/copywriting


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Refined contribution guidelines with clearer style guidance for filler
words, terminology (including “Backend” hyphenation), abbreviation
usage, and updated wording examples.
* Updated the foundations quickstart wording to “Utilize shadcn/ui”
under setup guidance.

* **Chores**
* Expanded MDX linting guidance to flag filler/marketing language, vague
verbs, formal corporate phrasing, apologies, human-language punctuation
variants, and certain Latin phrases.
* Adjusted related lint preferences and downgraded several checks to
**WARNING** for a less disruptive experience.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Miranda Limonczenko <miranda@supabase.io>
 2026-06-15 09:55:48 -07:00
Jeremias Menichelli 37357288cf fix: Improve mermaid notation for markdown content and add contriburting instructions (#46679) 2026-06-05 17:12:21 +02:00
Danny WhiteandChris Chinchilla 9c03ad6b02 chore(docs): migrate Admonition labels to titles (#46053) 
## What kind of change does this PR introduce?

Docs update. Related to DEPR-551.

## What is the current behavior?

Docs MDX still uses the legacy `label` prop for Admonitions, even though
#45618 added `title` and kept `label` only as a backwards-compatible
alias after #45302 was reverted in #45535.

## What is the new behavior?

Migrates Docs-owned Admonitions from `label=` to `title=` without
changing rendered copy, component APIs, Studio callsites, design-system
examples, or the legacy `label` alias.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Standardized admonition headings across the docs by switching how
admonition headings are provided (preserving all visible guidance and
examples). Content and instructions remain unchanged; this ensures
consistent rendering of callouts and improves uniformity across guides
and reference pages.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46053?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
 2026-05-18 19:00:09 +10:00
Andrew AgostiniandChris Chinchilla a6a598f824 docs: Fix broken urls (#40457) 
* docs: update link to Vecs Python source code in developers guide

* docs: update README to remove outdated GDScript links. These repos have been deleted

* docs: update links in CONTRIBUTING.md for consistency and accuracy

* docs: update Twilio verification service link

* docs: update Mixpeek Python Client link in video search guide, remove link to missing code example

* docs: update GIN index link to point to PostgreSQL 16 documentation ('current' symantic no longer exists)

* docs: update Cloudflare Turnstile links to avoid 302 redirect

* docs: update LlamaIndex SupabaseVectorStore link to the correct documentation

* docs: update link to related issue for error message translation in auth-ui guide (to avoid 302 redirect)

* docs: update link from Next.js middleware to Next.js Proxy in auth-helpers guide to follow Next.js's new naming convention

* Update DEVELOPERS.md

* Update CONTRIBUTING.md

Direct to correct URL

* Update hybrid-search.mdx

Fix URL

* docs: renam Next.js middleware to proxy

* Update DEVELOPERS.md

Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>

---------

Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
 2025-11-28 08:58:11 +00:00
Nellie McKesson 3a88feebcc docs: fix broken partials link in CONTRIBUTING guide (#39081) 2025-09-29 18:00:35 +00:00
Julien Goux aa0fedfc39 chore: node v22 LTS compatibility for contributing (#30970) 
* chore: node v22 LTS compatibility for contributing

* missing assertions

* apply prettier
 2024-12-12 11:29:07 +01:00
Charis 27c752de17 docs: update contributing guide for new repo organization (#21470) 2024-02-23 13:13:13 -05:00
Charis 3b781ab6bb update and streamline all the docs readmes (#20201) 2024-01-08 13:49:42 -05:00
Kevin Grüneberg 129b3d927a chore: move specs to docs folder (#20136) 2024-01-03 18:54:23 +01:00
CharisandCopple 941d32dcdb docs: add contributing guide for docs (#19146) 
Co-authored-by: Copple <10214025+kiwicopple@users.noreply.github.com>
 2023-11-23 15:01:12 -05:00