supabase/apps/docs/style-guide/03-page-structure.md

How to structure a page

A well-structured document drastically reduces cognitive load. This document breaks down how to segment information so it can be found at the right time and place.

Chunking is a major principle of effective technical writing. Break things up. If there are too many chunks, group the chunks, and maybe break up some more. We want to avoid a "too long, didn't read" situation.

Apply this document when you add a page or move content around on an existing one.

If you're deciding	Read
Which document type to write, and how big it should be	Document types
Which reader question a chunk answers	Information types
How to order sections on the page	Grouping sections
How many items belong in one group	Chunking
How to open a long page and connect its sections	Navigation and glue
How to keep a page from going stale	Write timeless documentation
What to leave out of the repo	Keep internal context out

Document types

Supabase docs contain five types of document. Decide which one you need before you start writing.

Type	Purpose	Contains	Doesn't contain	Example
Explainer	Learn a topic	What it is, why, and when to use it	Instructions	Auth architecture
Tutorial	Finish a multi-feature goal	Procedures plus the reasoning	—	Build a Next.js app
Guide	Finish one task	Procedures in sequence	Background; link to an explainer	Passwordless logins
Reference	Look something up	Parameters, return types, samples	Context and use cases	JavaScript client
Troubleshooting	Resolve one error	The symptom, the cause, the fix	Feature overviews	Too many channels

Reference content is generated from spec files rather than hand-authored. See CONTRIBUTING.md for the reference pipeline.

Troubleshooting entries live in content/troubleshooting/ and use TOML frontmatter. Some sync from GitHub discussions, so check whether an entry exists before writing one.

Open a guide with a value statement

Name what the reader can do and why it matters to them. That's what tells a reader or an agent whether the page matches their goal.

• Recommended: Restrict access to a shared table with Row Level Security. To learn how a policy is evaluated, see [Row Level Security](...).
• Not recommended: Several paragraphs about how Row Level Security works before stating what the reader can do.

Keep procedures focused on what the reader must do. Move substantial background into a separate section or an explainer and cross-reference the authoritative explanation rather than repeating it. This keeps the action path scannable and maintains one source of truth.

Topic size

Each type above is one unit of work for the reader. An explainer covers one topic. A guide covers one targeted task. A tutorial covers one multi-feature goal. A reference page covers one thing the reader looks up.

One unit per page

Enabling Row Level Security is one guide. Writing policies is a second, and designing a multi-tenant schema is a third. A reader who lands on the page from search should be able to finish what they came for. Link to the related pages.

Keep a short piece inside its parent

A fact or a principle is often one sentence. Put it in the section it qualifies. A heading whose only job is to point somewhere else is a link.

Give the next unit its own page

Split when a section has grown its own subsections and shares little with the rest of the page beyond the subject word. The new page takes the second task or the second concept, and this page links to it.

Chunking limits how many items sit in one group. Topic size limits what those items are about. A procedure can have six steps and still cover two tasks.

• Recommended: A passwordless email login guide with Send a one-time password and Verify the code.
• Not recommended: An Authentication page that also covers passwords, OAuth, and session storage.

Information types

The Information Mapping method names six types of information. Each answers a different reader question, and each has a form that suits it.

Type	Answers	Present with	Build it per
Procedure	How do I do it?	Numbered steps, or an if/then table	Procedures, Tables
Process	What is happening? How does it work?	A stage-by-stage description, or a when/then table	Tables, Diagrams
Structure	What are its parts?	A part and description table, or a labeled diagram	Tables, Diagrams
Principle	What should I do or not do?	Text, a list, or an admonition	Lists, Admonitions
Concept	What is it?	Text, a list, or a diagram	Lists, Diagrams
Fact	What are the facts?	Text, a list, or a table	Lists, Tables

Classify the content

1. Split the content into chunks. One chunk is one thing you're telling the reader.
2. For each chunk, ask which reader question it answers, and read its type off the table above.
3. Build each chunk in the form its Present with column names. A chunk already in a different form is a defect. Fix it.
4. Group the chunks by type, per Grouping sections.

Example below works one paragraph through these steps.

Separating the types

Separate a procedure, a process, a structure, or a concept

Each usually reads better in its own section. Procedure and process get blended most often, because both answer a question about how, and a reader following steps can't act on the process sentences.

Keep context out of the action path

A concept or a process tends to work better before the procedure or after it than threaded through the steps.

Let a principle or a fact ride along

Either is often a single sentence, so it can sit in the section it qualifies rather than getting one of its own. A fact about timing fits in the step it describes, and a principle can close the concept paragraph that motivates it.

Look again at a long paragraph

Past three or four sentences, it has often picked up a second kind of information. Label each sentence and see where the labels change.

Leave connective prose alone

An introduction, a transition, an outcome, and a navigation outline describe the page rather than the product, so none of this applies to them.

Example

Not recommended, because one paragraph blends a concept, a procedure, and a structure:

Row Level Security is a Postgres feature that restricts which rows a user can read
or write, and it's the main way to secure a table that several users share. Enable
it by running `alter table profiles enable row level security`, which takes effect
immediately. Be careful, because a table with Row Level Security enabled and no
policy returns no rows to every client, so write a policy before you deploy. The
`using` clause of a policy accepts any expression that returns a boolean.

Recommended, with each type in the presentation that suits it:

## Row Level Security

Row Level Security restricts which rows a user can read or write. It's the main way
to secure a table that several users share.

### Enable Row Level Security

1. Run `alter table profiles enable row level security`. The change takes effect
   immediately.
2. Write a policy that grants the access your app needs.

<Admonition type="caution">

A table with Row Level Security enabled and no policy returns no rows to `anon` or
`authenticated`. Write a policy before you deploy.

</Admonition>

### Policy reference

The `using` clause accepts any expression that returns a boolean.

Grouping sections

Information types apply at the page level too. Group sections of related types together, and keep the procedure group unbroken so context doesn't interrupt the action path.

Classify a section by what the reader is doing in it

On a page about tables every section is about tables, so subject matter tells you nothing. A reader opens a section on schemas to understand something, so it's context.

Split a section that serves two types

Filing it under the larger half buries the other one. Give the new half a heading, keep the heading text of the half that stays, and cross-reference the two.

One order that works: a short concept opener, then procedures, then concept and process, then structure and fact.

## What is a table?                    <- concept opener
## Creating and managing tables        <- procedures
### Creating tables
### Securing your tables
### Loading data
## How tables are organized            <- concept and process
### Primary keys
### Relationships between tables
### Schemas
## Reference                           <- structure and fact
### Data types

Chunking

Apply the Information Mapping chunking principle: present 5 ± 1 related items at a time. That gives readers a manageable chunk of four to six. Aim for the lower end when the task is complex or unfamiliar.

Information Mapping gives 7 ± 2 as the general limit and 5 ± 1 for content read on a screen. Screen reading is less accurate than the same content on paper. Supabase docs are read on a screen, so 5 ± 1 applies.

If a procedure has more than six steps, group related steps into named phases or smaller procedures. Don't add steps to reach a minimum. The range organizes information.

The same limit applies to sections in a group. A page with ten top-level headings needs grouping. Reordering them changes nothing.

Headings and lists are the other half of chunking. A long stretch of prose with no heading gives a reader no way in and no way to skip. A reader navigating by heading has nothing to navigate. Where a paragraph has grown past its one topic, a heading or a list usually serves better than a longer paragraph.

A lookup surface is the exception. When a reader arrives to find one entry rather than to read the page, the entries carry their own order: alphabetical, or the order of an API. Grouping them into fives would hide what they came for.

A reference document is the same case. A reader opens this style guide to find one rule. Its sections are a list to scan, not a sequence to hold in memory.

For how to format the steps inside a procedure, see 02-elements.md.

Navigation and glue

Begin a long guide with a short outline of its major section groups

Link to each group and say when a reader should use it. Don't add section navigation to a short guide when its headings already fit on one screen.

Connect your app to Postgres through a connection pooler, a direct connection, or a
Supabase client library.

- [Choose a connection method](#choose-a-connection-method) compares the options and
  their trade-offs. Start here if you aren't sure which one fits your app.
- [Connect your app](#connect-your-app) has the steps for each method.
- [Connection parameters](#connection-parameters) lists every parameter and its
  default.

Each link says what the reader gets from that group, so someone who already knows which method they want goes straight to the procedures.

Connect contextual sections to their procedures

Do this when the relationship helps readers navigate. Add a brief introduction to each section group, a transition when the information type changes, and an outcome after a procedure. Add links selectively rather than linking every adjacent section.

• Group introduction: The following sections cover each connection method in turn. Every method needs your project reference, which you find on the project settings page.
• Transition where the type changes: Those are the mechanics of opening a connection. To understand why a pooled connection behaves differently under load, see [Connection pooling](...).
• Outcome after a procedure: Your app now connects through the pooler. Queries that used to fail at the connection limit queue instead.

Write timeless documentation

Document the product as it is now. Language that fixes a page to a moment goes stale, and a reader can't tell whether currently was written last week or three years ago.

Avoid words that anchor a sentence to a point in time

Avoid	Avoid	Avoid
as of this writing	existing	now
currently	future, in the future	old, older
does not yet	latest	presently, at present
eventually	new, newer	soon

WORD_LIST.md has entries for the two that come up most, currently and latest, new, and soon.

• Recommended: The emulator supports the following filters.
• Not recommended: The emulator now supports the following filters.

Don't promise a feature that hasn't shipped

Coming soon, will be available, and once finalized all decay into inaccuracy, and a reader can't act on any of them. When a phased rollout is real, state the criteria that decide who has it: Available to organizations on Pro and Enterprise plans.

Don't ship a placeholder page

A page saying This is a placeholder or More details coming soon promises content on no schedule. Wait until the page is worth reading, or ship the smaller thing that's true today. When navigation structure forces a page to exist, link out to resources that are complete.

Exceptions

Changelog, release notes, and blog content are time-sensitive by nature, and referencing the future is their job. Procedural content can use a time word for a state change the reader causes: The table now appears in the editor.

Keep internal context out

Supabase docs are open source. Keep planning notes, unshipped features, business intent, and references to ticketing systems out of the repo. Put review-time context in the pull request description and product context in the team's project-management tool.