Docs Content

Supabase docs authoring

Sources of truth

Before changing docs content:

• Read apps/docs/CONTRIBUTING.md for content types, structure, components, and

style.

• Read apps/docs/WORD_LIST.md for preferred terminology, spelling, and

capitalization.

• Inspect nearby content of the same type and the relevant navigation section

before deciding on file placement or structure. Guides, explainers, and

tutorials live under apps/docs/content/guides. Troubleshooting entries live

under apps/docs/content/troubleshooting and use TOML frontmatter — follow

_template.mdx in that directory rather than a guide's YAML frontmatter.

Reference docs are generated from apps/docs/spec and library source, so

look for the spec file or repo definition instead of editing rendered output

directly.

When guidance conflicts, follow apps/docs/CONTRIBUTING.md. Match literal code,

API names, UI labels, and third-party product names even when they differ from the

word list.

Writing workflow

• Identify the document type: explainer, tutorial, guide, or reference, per

apps/docs/CONTRIBUTING.md. A guide is a concise procedure for a targeted

task; a tutorial covers a larger goal and includes more explanatory context;

an explainer is conceptual and prose-based; reference content is factual,

like a dictionary entry. Troubleshooting entries follow their own TOML

structure rather than these four types.

• Define the reader's goal and prerequisites before drafting.
• Classify substantial sections as contextual, procedural, or reference content.

In a mixed page, group sections by information type so that context doesn't

interrupt the procedural path.

• For a long or mixed page, add a short introduction that links to its major

section groups and tells readers when to use each one. Skip this navigation

when a short page is already easy to scan.

• Connect contextual sections to their corresponding procedures when useful.

Add introductions to section groups, transitions between information types,

and outcomes after procedures. Don't link every adjacent section.

• Use second person, present tense, short paragraphs, and ordered steps for

sequential actions.

• Search apps/docs/WORD_LIST.md when introducing or reviewing technical terms,

UI actions, abbreviations, and potentially ambiguous language.

• Keep code samples executable in their stated context and consistent with

repository formatting. Clearly mark intentionally omitted code. Use lowercase

SQL keywords.

• Reuse repeated content through apps/docs/content/_partials instead of copying

it.

10. Add new guide, explainer, and tutorial pages to

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts.

File placement alone doesn't add a page to navigation. Troubleshooting

entries are indexed automatically and don't need a navigation entry.

11. Use /docs/... paths for pages in Supabase docs and site-root paths such as

/dashboard for pages outside docs. Use descriptive link text and sparse

admonitions with the appropriate severity.

Validation

From apps/docs, run:

pnpm lint:mdx
pnpm build:guides-markdown

pnpm lint:mdx covers all content under apps/docs/content, including

troubleshooting entries. pnpm build:guides-markdown only applies to guides,

explainers, and tutorials.

From the repository root, run pnpm format to apply Prettier to any changed

MDX (and other) files. This enforces repo-wide formatting rules, including

lowercase SQL keyword casing in code samples.

Run broader type checking or tests when the change affects MDX components,

content listings, navigation code, or generated output.

For a mixed page, verify that context and procedures are grouped, introductory

navigation links resolve to the intended sections, related context and procedures

are cross-referenced where useful, and transitions make the reading path clear.

Treat lint replacements as suggestions when context matters. Rewrite the sentence

instead of applying a replacement that changes its technical meaning.

Anchor IDs are generated from heading text at render time, and nothing in CI

checks that #anchor links still resolve. Before renaming, removing, or

substantially rewording a heading, run

grep -rn "#<old-anchor-slug>" apps/docs/content to find in-page and

cross-file links that target it, and update every match. If a heading needs a

stable anchor independent of its wording, pin it with a custom anchor, for

example ## Some heading [#some-heading].