mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 01:15:03 +03:00
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 -->
This commit is contained in:
Miranda Limonczenko authored and GitHub committed
1 parent
f5fcecf3d7
commit
36371de151
8 files changed
+44
-439
No files matched your search
+2
-2
@@ -74,8 +74,8 @@ reviews:
|
||||
Flag style, terminology, and structure issues as usual. When a page has two or
|
||||
more of them, add one comment pointing the author at the `/write-the-docs` skill
|
||||
for new content or `/edit-the-docs` for an existing page (canonical files in
|
||||
`.agents/skills/`); both apply apps/docs/CONTRIBUTING.md and
|
||||
apps/docs/WORD_LIST.md. Skip that pointer on a single issue, so it stays a
|
||||
`.agents/skills/`); both apply the docs style guide in
|
||||
apps/docs/style-guide/. Skip that pointer on a single issue, so it stays a
|
||||
signal that the author isn't using the skills rather than boilerplate.
|
||||
- path: '{apps,packages}/**/*.{tsx,jsx,css,mdx}'
|
||||
instructions: |
|
||||
|
||||
@@ -38,10 +38,9 @@ Provide a clear numbered procedure that the PR reviewer can walk through.
|
||||
1. For example, `Open the live and preview links side-by-side.`
|
||||
2. For example, `See the issue is fixed.`
|
||||
|
||||
|
||||
## Checklist
|
||||
|
||||
Check all before review:
|
||||
|
||||
- [ ] I have read [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
|
||||
- [ ] If I wrote a new docs topic or edited an existing topic, I used the `/write-the-docs` or `/edit-the-docs` skill, which references [WORD_LIST](https://github.com/supabase/supabase/blob/master/apps/docs/WORD_LIST.md) and the docs [CONTRIBUTING](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md) guide
|
||||
- [ ] If I wrote a new docs topic or edited an existing topic, I used the `/write-the-docs` or `/edit-the-docs` skill, which applies the docs [style guide](https://github.com/supabase/supabase/tree/master/apps/docs/style-guide)
|
||||
@@ -22,7 +22,6 @@ examples/slack-clone/nextjs-slack-clone/full-schema.sql
|
||||
# ignore files with custom js formatting
|
||||
apps/studio/public
|
||||
apps/**/.turbo
|
||||
apps/docs/CONTRIBUTING.md
|
||||
apps/docs/__generated__
|
||||
# Generated by apps/docs/internals/generate-markdown-manifest.ts
|
||||
apps/docs/lib/markdown-manifest.ts
|
||||
|
||||
@@ -60,10 +60,10 @@ Never hand-edit generated files: `packages/api-types/types/**`, `**/routeTree.ge
|
||||
|
||||
## Skills
|
||||
|
||||
The skills in `.agents/skills/` are the source of truth for conventions — load the relevant ones before working, don't guess:
|
||||
The skills in `.agents/skills/` are the source of truth for conventions. Load the relevant ones before working, don't guess. One exception: for docs **content** style, `apps/docs/style-guide/` is the source of truth and the docs skills are the process that applies it.
|
||||
|
||||
- `copywriting` — any user-facing text, anywhere in the monorepo
|
||||
- `pm-the-docs` / `write-the-docs` / `edit-the-docs` / `ask-the-docs` / `review-the-docs` — anything under `apps/docs` (see `apps/docs/CONTRIBUTING.md` for the authoring skill model)
|
||||
- `pm-the-docs` / `write-the-docs` / `edit-the-docs` / `ask-the-docs` / `review-the-docs` — anything under `apps/docs` (see `apps/docs/CONTRIBUTING.md` for the authoring skill model, and `apps/docs/style-guide/` for the content style rules they apply)
|
||||
- `telemetry-standards` — PostHog events, `packages/common/telemetry-constants.ts`
|
||||
- `dev-toolbar-review` — `packages/dev-tools`, `packages/common/posthog-client.ts`, `packages/common/feature-flags.tsx`
|
||||
- `safe-sql-execution` — any code that builds or executes SQL against user databases
|
||||
|
||||
+14
-2
@@ -2,9 +2,21 @@
|
||||
|
||||
Next.js app router + MDX. Dev server: `pnpm dev:docs` → http://localhost:3001/docs (the bare `/` 404s).
|
||||
|
||||
## Skills — load before working
|
||||
## Style guide
|
||||
|
||||
`pm-the-docs`, `write-the-docs`, `edit-the-docs`, `ask-the-docs`, and `review-the-docs` back the docs authoring process — see `CONTRIBUTING.md` for which stage each covers. For architecture questions (MDX pipeline, GraphQL endpoint, search embeddings, federated docs, build pipeline), `ask-the-docs` has the reference notes.
|
||||
`style-guide/` holds the docs style guide as plain markdown.
|
||||
|
||||
- `style-guide/README.md` — what the guide covers, how the files are ordered, and the external references it defers to
|
||||
- `style-guide/WORD_LIST.md` — terminology; check it before drafting and again before opening a PR
|
||||
- `style-guide/01-voice-and-tone.md` — person, tense, sentence length, brevity
|
||||
- `style-guide/02-elements.md` — admonitions, code blocks, procedures, tabs, images
|
||||
- `style-guide/03-page-structure.md` — document type, section grouping, chunking
|
||||
|
||||
Load the file you need rather than the whole directory. No tool enforces the guide, so applying it is the author's job, or the skill's.
|
||||
|
||||
## Skills
|
||||
|
||||
Load these before working. `pm-the-docs`, `write-the-docs`, `edit-the-docs`, `ask-the-docs`, and `review-the-docs` back the docs authoring process. See `CONTRIBUTING.md` for which stage each covers. They apply the style guide above. For architecture questions (MDX pipeline, GraphQL endpoint, search embeddings, federated docs, build pipeline), `ask-the-docs` has the reference notes.
|
||||
|
||||
## Test requirements
|
||||
|
||||
|
||||
+23
-428
@@ -4,7 +4,7 @@ Our docs help developers to get started and keep succeeding with Supabase. We we
|
||||
|
||||
If you'd like to contribute, see our list of [recommended issues](https://github.com/supabase/supabase/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation+label%3A%22help+wanted%22). We also welcome you to open a PR or a new issue with your question.
|
||||
|
||||
Here are some general guidelines on writing docs for Supabase. If you write with an AI coding agent, these skills apply the guidelines for you:
|
||||
How to write a docs page is covered by the [style guide](./style-guide/README.md). This file covers repo mechanics. If you write with an AI coding agent, these skills apply the style guide for you:
|
||||
|
||||
- `/write-the-docs` to draft a new page.
|
||||
- `/edit-the-docs` to revise an existing page.
|
||||
@@ -13,84 +13,25 @@ Here are some general guidelines on writing docs for Supabase. If you write with
|
||||
|
||||
See [AI agent skills for docs authoring](#ai-agent-skills-for-docs-authoring) for the full set, including the skills that help you frame a page and place it in the information architecture.
|
||||
|
||||
## General principles
|
||||
## Style guide
|
||||
|
||||
Write helpful, concise, and understandable documentation. We have a global audience whose members speak different native languages.
|
||||
The [style guide](./style-guide/README.md) covers how to write a docs page: voice,
|
||||
page structure, which components to use, and terminology. Start at its
|
||||
[README](./style-guide/README.md) for what the guide covers and how the files are ordered.
|
||||
|
||||
To make docs as clear as possible:
|
||||
| File | Covers |
|
||||
| ------------------------------------------------------------------------ | -------------------------------------------------- |
|
||||
| [`style-guide/WORD_LIST.md`](./style-guide/WORD_LIST.md) | Terminology, spelling, capitalization |
|
||||
| [`style-guide/01-voice-and-tone.md`](./style-guide/01-voice-and-tone.md) | Person, tense, sentence length, brevity |
|
||||
| [`style-guide/02-elements.md`](./style-guide/02-elements.md) | Admonitions, code blocks, procedures, tabs, images |
|
||||
| [`style-guide/03-page-structure.md`](./style-guide/03-page-structure.md) | Document type, section grouping, chunking |
|
||||
|
||||
- Write for the user. Think about what task they want to complete by reading your doc. Tell them what, and only what, they need to know.
|
||||
- Write like you talk. Conversational English is easier for a global audience to understand and localize. Many readers who use English as an additional language learn conversational rather than academic English. Use words and sentences that sound natural when speaking. Cut unnecessary words. Read your writing out loud to help you choose the clearest and simplest phrases.
|
||||
- Prefer short, direct sentences. Express one relationship at a time, and avoid unnecessary compound structures. This makes each sentence easier to understand, localize, and interpret consistently.
|
||||
- Cover one topic in each paragraph. Start a new paragraph whenever you change the topic, or when you move between [information types](#information-types). Don't worry about paragraphs being too short.
|
||||
- Avoid using idioms and colloquialisms, such as `piece of cake`. These phrases are often specific to a region or culture.
|
||||
- Refer to the reader as `you`. Don't use `we` to refer to the reader. Use `we` only to refer to the Supabase team.
|
||||
|
||||
## Information types
|
||||
|
||||
Separating kinds of information helps a reader reach what they came for and retain it afterward. Someone scanning for a command shouldn't have to read past a definition to find it, and someone reading to understand shouldn't have to step around instructions. Blended prose slows down both, along with an AI agent trying to answer a question from the page, and little of it sticks.
|
||||
|
||||
The [Information Mapping](https://support.informationmapping.com/hc/en-us/articles/213446789-Present-your-information-in-a-clear-and-consistent-way) method names six kinds, each answering a different reader question:
|
||||
|
||||
| Type | Answers | Present with |
|
||||
| --- | --- | --- |
|
||||
| Procedure | How do I do it? | Numbered steps, or an if/then table |
|
||||
| Process | What is happening? How does it work? | A stage-by-stage description, or a when/then table |
|
||||
| Structure | What are its parts? | A part and description table, or a labeled diagram |
|
||||
| Principle | What should I do or not do? | Text, a list, or an admonition |
|
||||
| Concept | What is it? | Text, a list, or a diagram |
|
||||
| Fact | What are the facts? | Text, a list, or a table |
|
||||
|
||||
### Recommendations
|
||||
|
||||
- **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.
|
||||
|
||||
### Examples
|
||||
|
||||
Not recommended, because one paragraph blends a concept, a procedure, and a structure:
|
||||
|
||||
```md
|
||||
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:
|
||||
|
||||
```md
|
||||
## 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 every
|
||||
client. Write a policy before you deploy.
|
||||
|
||||
</Admonition>
|
||||
|
||||
### Policy reference
|
||||
|
||||
The `using` clause accepts any expression that returns a boolean.
|
||||
```
|
||||
The rest of this file covers repo mechanics: where content lives, how to add a page,
|
||||
and how the reference docs are generated.
|
||||
|
||||
## AI agent skills for docs authoring
|
||||
|
||||
Use these skills for every docs change you make with an AI coding agent: `/write-the-docs` to draft, and `/edit-the-docs` to revise an existing page. They apply this guide and the [word list](./WORD_LIST.md), so you don't have to hold either one in your head.
|
||||
Use these skills for every docs change you make with an AI coding agent: `/write-the-docs` to draft, and `/edit-the-docs` to revise an existing page. They apply the [style guide](./style-guide/README.md), so you don't have to hold it in your head.
|
||||
|
||||
Skills work in any agent that reads `.agents/skills/`, such as Claude Code, Cursor, or Codex. Invoke a skill with `/name`, for example `/write-the-docs`. The canonical files live in `.agents/skills/` (`.claude/skills` is a symlink).
|
||||
|
||||
@@ -98,118 +39,18 @@ Skills work in any agent that reads `.agents/skills/`, such as Claude Code, Curs
|
||||
|
||||
Use the [Write the docs](../../.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md) checklist when product intent and code drive the change: net-new pages, or revising/restructuring existing ones.
|
||||
|
||||
| Skill | Checklist stage | Use for |
|
||||
| --- | --- | --- |
|
||||
| [`pm-the-docs`](../../.agents/skills/pm-the-docs/SKILL.md) | Frame / shape | Audience, stage, why, content type, cross-repo scope (universe when you have Supabase org access, else OSS path) |
|
||||
| [`ask-the-docs`](../../.agents/skills/ask-the-docs/SKILL.md) | Frame / shape | Docs-app architecture, IA placement, where content lives |
|
||||
| [`write-the-docs`](../../.agents/skills/write-the-docs/SKILL.md) | Draft | Draft or revise content grounded in intent and code |
|
||||
| [`test-the-docs`](../../.agents/skills/test-the-docs/SKILL.md) | Draft / self-review | Run snippets in a Docker-isolated stack; verification report |
|
||||
| [`review-the-docs`](../../.agents/skills/review-the-docs/SKILL.md) | Self-review / PR review | Checking a draft; verify a PR |
|
||||
| Skill | Checklist stage | Use for |
|
||||
| ------------------------------------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| [`pm-the-docs`](../../.agents/skills/pm-the-docs/SKILL.md) | Frame / shape | Audience, stage, why, content type, cross-repo scope (universe when you have Supabase org access, else OSS path) |
|
||||
| [`ask-the-docs`](../../.agents/skills/ask-the-docs/SKILL.md) | Frame / shape | Docs-app architecture, IA placement, where content lives |
|
||||
| [`write-the-docs`](../../.agents/skills/write-the-docs/SKILL.md) | Draft | Draft or revise content grounded in intent and code |
|
||||
| [`test-the-docs`](../../.agents/skills/test-the-docs/SKILL.md) | Draft / self-review | Run snippets in a Docker-isolated stack; verification report |
|
||||
| [`review-the-docs`](../../.agents/skills/review-the-docs/SKILL.md) | Self-review / PR review | Checking a draft; verify a PR |
|
||||
|
||||
### Edit existing pages
|
||||
|
||||
Use [`edit-the-docs`](../../.agents/skills/edit-the-docs/SKILL.md) for style, structure, or brevity on an existing page when you are not changing the product story.
|
||||
|
||||
## Document types
|
||||
|
||||
Supabase docs contain four types of documents. Before you start writing, think about what type of doc you need.
|
||||
|
||||
### Explainers
|
||||
|
||||
Explainers help the reader to learn a topic. They are conceptual and mostly prose-based. They can include:
|
||||
|
||||
- A description of _what_ a feature is
|
||||
- Some reasons _why_ it is useful
|
||||
- Some examples of _when_ to use it
|
||||
- A high-level explanation of _how_ it works
|
||||
|
||||
Explainers don't include:
|
||||
|
||||
- Instructions on how to use it
|
||||
|
||||
### Tutorials
|
||||
|
||||
Tutorials are goal-oriented. They help a reader to finish a large, complex goal, such as setting up a web app that uses multiple Supabase features.
|
||||
|
||||
Tutorials mix prose explanations with procedures. Procedures are lists of steps for the reader to follow. Tutorials provide context for why certain instructions are given.
|
||||
|
||||
For inspiration, see [an example of a tutorial](https://supabase.com/docs/guides/getting-started/tutorials/with-nextjs).
|
||||
|
||||
### Guides
|
||||
|
||||
Guides are also goal-oriented, but they focus on shorter, more targeted tasks. For example, a guide might explain how to set up user login for an app.
|
||||
|
||||
Guides contain mostly procedures: concise steps that readers can follow in sequence.
|
||||
|
||||
A value statement makes a good opener: 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.
|
||||
|
||||
Keep procedures focused on what the reader must do. Move substantial background or conceptual explanations into a separate section or an explainer. Cross-reference the authoritative explanation instead of repeating it in the procedure. This keeps the action path scannable, gives readers optional depth, and maintains one source of truth.
|
||||
|
||||
- **Recommended**: `Restrict access to a shared table with Row Level Security. To learn how a policy is evaluated, see [Row Level Security](...).`
|
||||
- **Not recommended**: Begin with several paragraphs about how Row Level Security works before stating what the reader can do.
|
||||
|
||||
**Mixed information types:** [Information types](#information-types) apply at the page level too. Group sections of related types together, and try to keep the procedure group unbroken so context doesn't interrupt the action path. A section serving two types can be split, with a cross-reference between the halves.
|
||||
|
||||
Classify a section by what the reader is doing in it, not by what it's about. 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.
|
||||
|
||||
One order that works: a short concept opener, then procedures, then concept and process, then structure and fact.
|
||||
|
||||
```text
|
||||
## 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
|
||||
```
|
||||
|
||||
**Navigation:** Begin a long guide with a short outline of its major section groups. Link to each group and state when a reader should use it. Don't add section navigation to a short guide when the headings are already easy to scan.
|
||||
|
||||
For example, an introduction to a long guide that mixes information types:
|
||||
|
||||
```md
|
||||
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.
|
||||
|
||||
**Cross-references and glue:** Connect contextual sections to their corresponding procedures 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.`
|
||||
|
||||
For inspiration, see [an example of a guide](/docs/guides/auth/auth-email-passwordless).
|
||||
|
||||
### Reference
|
||||
|
||||
References are factual and to the point. Think of dictionary entries.
|
||||
|
||||
References include:
|
||||
|
||||
- Function parameters
|
||||
- Return types
|
||||
- Code samples
|
||||
- Warnings about critical errors, such as missteps that can cause data loss
|
||||
|
||||
References don't include:
|
||||
|
||||
- Explanations of the context for a feature
|
||||
- Examples of use cases
|
||||
- Multi-step instructions
|
||||
|
||||
## Repo organization
|
||||
|
||||
Most docs pages are contained in the `apps/docs/content` directory. Some docs sections are federated from other repositories, for example [`pg_graphql`](https://github.com/supabase/pg_graphql/tree/master/docs). Reference docs are generated from spec files in the `spec` directory.
|
||||
@@ -293,97 +134,9 @@ If you copy the same content multiple times across different files, create a **p
|
||||
|
||||
To use a partial, import it into your MDX file. You can also set up a partial to automatically import by including it in the `components` within [`apps/docs/features/docs/MdxBase.shared.tsx`](https://github.com/supabase/supabase/blob/master/apps/docs/features/docs/MdxBase.shared.tsx).
|
||||
|
||||
## Components and elements
|
||||
## Content listings
|
||||
|
||||
Docs include normal Markdown elements such as lists and custom components such as admonitions, also known as callouts.
|
||||
|
||||
Here are some guidelines for using elements:
|
||||
|
||||
### Admonitions
|
||||
|
||||
Admonitions draw reader attention to an important point or an aside. They highlight important information, but get less effective if they're overused.
|
||||
|
||||
Use an admonition when a reader might otherwise miss information that affects the outcome of their task, or when you want to separate helpful but optional guidance from the main flow. Don't use an admonition for information that belongs in the main explanation or procedure.
|
||||
|
||||
Use admonitions sparingly. Don't stack them on top of each other or use them as decoration.
|
||||
|
||||
Begin every admonition with its impact and purpose: the "so what." Use the first sentence to tell the reader why the information matters, such as what could happen, what changes, or what benefit they gain. Add background or instructions after the impact is clear.
|
||||
|
||||
For example:
|
||||
|
||||
- **Recommended**: `Deleting this project permanently removes its database and backups. Export any data that you want to keep before you continue.`
|
||||
- **Not recommended**: `Before you continue, there are a few things that you should know about project deletion.`
|
||||
|
||||
Choose the appropriate `type` for your admonition:
|
||||
|
||||
- `danger`: Warn about actions or conditions that could cause data loss, expose sensitive data, or create another severe and difficult-to-reverse outcome. State the consequence first, and then explain how to avoid it.
|
||||
- `deprecation`: Identify a deprecated feature or behavior. State how the change affects the reader, and then provide the supported alternative or migration path.
|
||||
- `caution`: Warn about behavior that could cause bugs, failed operations, unexpected results, or serious inconvenience but doesn't rise to the severity of `danger`.
|
||||
- `note`: Highlight an important prerequisite, constraint, clarification, or optional shortcut that doesn't represent a risk. If the information is essential to completing a step, include it in the procedure instead.
|
||||
|
||||
Structure an admonition with these props and content:
|
||||
|
||||
- `title` (optional): Add a short callout title. Don't put Markdown or HTML headings inside an admonition. If the content needs a heading to structure the page, move the heading and its section outside the admonition.
|
||||
- `children`: Add rich body content such as paragraphs, lists, links, and code.
|
||||
- `actions` (optional): Add standalone calls to action so they remain separate from the body content. Keep contextual links and interactive examples in the body when they are part of the explanation.
|
||||
|
||||
```mdx
|
||||
<Admonition
|
||||
type="note"
|
||||
title="Optional title"
|
||||
actions={<Button>Continue</Button>}
|
||||
>
|
||||
|
||||
Your content here
|
||||
|
||||
</Admonition>
|
||||
```
|
||||
|
||||
### Blockquotes
|
||||
|
||||
Don't use blockquotes.
|
||||
|
||||
### Code blocks
|
||||
|
||||
Keep code lines short to avoid scrolling. For example, you can split long shell commands with `\`.
|
||||
|
||||
- **JavaScript/TypeScript**
|
||||
|
||||
The `supabase` repository uses Prettier, which also formats JS/TS in code blocks. Your PR is blocked from merging if the Prettier check fails. From the repository root, run `pnpm format`, or set up automatic formatting in your IDE.
|
||||
|
||||
- **SQL**
|
||||
|
||||
Prefer lowercase for SQL. For example, `select * from table` rather than `SELECT * FROM table`.
|
||||
|
||||
Optionally specify a filename for the code block by including it after the opening backticks and language specifier:
|
||||
|
||||
````md
|
||||
```ts environment.ts
|
||||
|
||||
```
|
||||
````
|
||||
|
||||
Optionally highlight lines by using `mark=${lineNumber}`.
|
||||
|
||||
````md
|
||||
```js mark=12:13
|
||||
|
||||
```
|
||||
````
|
||||
|
||||
### Emphasis
|
||||
|
||||
Use **bold**, _italics_, and `code` formatting for distinct purposes. Don't use them interchangeably or to add visual emphasis alone.
|
||||
|
||||
- **Bold**: Mark UI labels the reader interacts with, such as buttons, menu items, and field names. For example, `Click **Save**.` Also use bold for a term the reader must not miss, such as `**Never** commit your service role key.` Bold is also the convention for an inline label that opens a paragraph or a list item, such as `**Recommended**:` or `**Navigation:**`.
|
||||
- _Italics_: Introduce a new term the first time you define it, or reference a title, such as a book or a third-party product name written in italics by convention. Use italics sparingly. Don't use italics for UI labels or for general emphasis.
|
||||
- `Code`: Mark anything the reader types or copies verbatim, or anything the system reads literally. This includes filenames, paths, commands, flags, environment variables, function and parameter names, configuration keys, and literal values. For example, `` Set `SUPABASE_URL` in your `.env` file. ``
|
||||
|
||||
If a phrase fits more than one category, pick the most specific one. A command name is `code`, not **bold**, even though the reader also interacts with it.
|
||||
|
||||
### Content listings
|
||||
|
||||
Overview and index pages use a single `<ContentListings id="..." />` component for curated link sections such as "Get started", "Next steps", "Examples", or "Resources". Refer to [`storage.data.ts`](data/content-listings/storage.data.ts) and [`storage.mdx`](content/guides/storage.mdx) for a full example.
|
||||
Overview and index pages use a single `<ContentListings id="..." />` component for curated link sections. For when to use one, see [the style guide](./style-guide/02-elements.md#content-listings). Refer to [`storage.data.ts`](data/content-listings/storage.data.ts) and [`storage.mdx`](content/guides/storage.mdx) for a full example.
|
||||
|
||||
**Prompt to add content listings:**
|
||||
|
||||
@@ -403,164 +156,6 @@ Run `pnpm test:local lib/content-listings.test.ts` from apps/docs.
|
||||
|
||||
Code snippets for manually adding content listings are available in [`.vscode/content-listing.code-snippets`](../../.vscode/content-listing.code-snippets). Use `cl-data` for a data export with a namespaced ID. Use `cl-inline` for an MDX component.
|
||||
|
||||
|
||||
### Footnotes
|
||||
|
||||
Don't use footnotes.
|
||||
|
||||
### Graphs
|
||||
|
||||
Render diagrams, including flowcharts, sequence diagrams, and entity-relationship diagrams, by writing a fenced code block with `mermaid` as the language. The MDX renderer routes these blocks through the shared `Mermaid` component, so theming follows light and dark mode automatically.
|
||||
|
||||
For the full list of supported diagram types and their syntax, see the [official Mermaid diagram reference](https://mermaid.js.org/intro/syntax-reference.html).
|
||||
|
||||
Sequence diagram:
|
||||
|
||||
````mdx
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant Browser
|
||||
participant Supabase
|
||||
|
||||
User->>Browser: Clicks "Sign in"
|
||||
Browser->>Supabase: Request authorization
|
||||
Supabase->>Browser: Return token
|
||||
```
|
||||
````
|
||||
|
||||
The `flowchart` keyword accepts a direction such as `LR` or `TD`:
|
||||
|
||||
````mdx
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["content/**/*.md"] -->|Contentlayer| B[MDX]
|
||||
B --> C[Rehype]
|
||||
C -->|Our Plugin| D[SVG]
|
||||
D -->|Base64| E[Embedded Images]
|
||||
```
|
||||
````
|
||||
|
||||
A few tips:
|
||||
|
||||
- Use a standard Mermaid diagram keyword, such as `sequenceDiagram`, `flowchart`, or `erDiagram`, on the first line of the block.
|
||||
- Keep diagrams focused on a single flow or concept. If a diagram gets too dense, split it into multiple smaller diagrams.
|
||||
- Wrap node labels that contain special characters in double quotes. Special characters include `*`, `/`, spaces, and punctuation. For example, use `A["content/**/*.md"]`.
|
||||
- Don't hardcode colors. The component themes the diagram automatically so it matches both light and dark mode.
|
||||
- Use diagrams to support the prose, not replace it. Explain the key takeaway in text near the diagram.
|
||||
|
||||
### Images
|
||||
|
||||
Images are uploaded in the `apps/docs/public/img` folder.
|
||||
|
||||
For vector illustrations, use `.svg` files. For screenshots and non-vector graphics, use `.png` files. Supported browsers receive `.webp` versions automatically.
|
||||
|
||||
Redact any sensitive information, such as API keys.
|
||||
|
||||
### Links
|
||||
|
||||
Use descriptive link text that tells the reader where the link goes. This is important for accessibility. For example, don't use `here` as link text.
|
||||
|
||||
Keep link text concise. Use the shortest part of the link that is descriptive enough. For example, `see the [reference section](/link)` rather than `[see the reference section](/link)`.
|
||||
|
||||
Don't include the `https://supabase.com` origin when linking to pages on `supabase.com`. Use a `/docs/...` path for a page in Supabase docs, such as `[getting started](/docs/guides/getting-started)`. Use a site-root path for a page outside docs, such as `[open the Supabase Dashboard](/dashboard)`.
|
||||
|
||||
### Procedures
|
||||
|
||||
Use a procedure when a human or agent must perform actions to reach an outcome. The procedural format makes that expectation explicit.
|
||||
|
||||
Write sequential actions as an ordered list. Begin each step with an imperative verb, and include one action or a closely related set of actions per step. Give the reader enough context to know where to act.
|
||||
|
||||
Apply the [Information Mapping chunking principle](https://informationmapping.com/blogs/news/writing-for-the-web-the-magical-number-seven-plus-or-minus-two) to procedures. Present 7 ± 2 related steps at a time. This gives readers a manageable chunk of five to nine actions. Aim for the lower end of the range when the task is complex or unfamiliar.
|
||||
|
||||
If a procedure has more than nine steps, group related steps into named phases or smaller procedures. If one step contains multiple distinct actions, split it into separate steps. Don't add steps to reach a minimum. The range is a guideline for organizing information, not a required procedure length.
|
||||
|
||||
An apparent one-step procedure can become two steps when there is a real orientation action. For example:
|
||||
|
||||
1. Open a terminal in your project directory.
|
||||
2. Run `supabase start`.
|
||||
|
||||
The first step establishes the operating context for both readers and agents. Don't add a redundant orientation step to a genuinely atomic instruction. For example, write `Click **Save**.` instead of adding `Locate the **Save** button` as a separate step.
|
||||
|
||||
### Lists
|
||||
|
||||
Use ordered lists for steps that must be taken one after the other. Use unordered lists when order doesn't matter.
|
||||
|
||||
Use Arabic numerals (`1`, `2`, `3`) for ordered lists and dashes (`-`) for unordered lists.
|
||||
|
||||
Don't nest lists more than two deep.
|
||||
|
||||
```md
|
||||
1. List item
|
||||
2. List item
|
||||
1. List item
|
||||
2. List item
|
||||
3. List item
|
||||
- List item
|
||||
- List item
|
||||
<!-- DON'T ADD ANOTHER LEVEL OF NESTING -->
|
||||
- Overly nested list item
|
||||
```
|
||||
|
||||
### Tabs
|
||||
|
||||
Use tabs to provide alternative instructions for different platforms or languages.
|
||||
|
||||
The optional `queryGroup` prop lets you link directly to a tab. For this example, use `/docs/my-page?packagemanager=npm`.
|
||||
|
||||
```
|
||||
<Tabs
|
||||
scrollable
|
||||
size="small"
|
||||
type="underlined"
|
||||
defaultActiveId="npm"
|
||||
queryGroup="packagemanager"
|
||||
>
|
||||
<TabPanel id="npm" label="npm">
|
||||
|
||||
// ...
|
||||
|
||||
</TabPanel>
|
||||
<TabPanel id="yarn" label="Yarn">
|
||||
|
||||
// ...
|
||||
|
||||
</TabPanel>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
### Videos
|
||||
|
||||
Include videos as table of contents (TOC) videos instead of placing them in the main text.
|
||||
|
||||
You can define a TOC video in the page frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
tocVideo: 'rzglqRdZUQE'
|
||||
---
|
||||
```
|
||||
|
||||
## Styling, formatting, and grammar
|
||||
|
||||
Grammar is useful when it makes your writing clearer. Use complete sentences by default because they identify the actor and action. This reduces ambiguity for readers, translators, and agents. Use sentence fragments only where they improve scanning, such as headings, labels, or short list items.
|
||||
|
||||
Headings guide the reader's eye and organize the page, but they don't carry information by themselves. Make the content beneath a heading understandable without relying on the heading. The first sentence can restate the heading, even if it sounds redundant. Readers often skim headings and then return to the section that interests them, so use the opening sentence to confirm the context.
|
||||
|
||||
Don't use parentheses for asides or supplementary information. Rewrite that information as part of the sentence or as a separate sentence. Use parentheses to introduce an acronym after spelling out its meaning, such as full-text search (FTS), or to mark an item as `(Optional)`. Parentheses that are required by Markdown links or code syntax aren't prose parentheticals.
|
||||
|
||||
That said, a few rules help keep the docs concise, consistent, and clear:
|
||||
|
||||
- Format headings in sentence case. Capitalize the first word and any proper nouns. All other words are lowercase. For example, `Set up authentication` rather than `Set Up Authentication`.
|
||||
- Use the Oxford comma. Place a comma before the `and` that marks the last item in a list. For example, use `functions, tables, and indexes` rather than `functions, tables and indexes`.
|
||||
- Use the present tense as much as possible. For example, `the AI assistant answers your question` rather than `the AI assistant will answer your question`.
|
||||
|
||||
## Word usage and spelling
|
||||
|
||||
Use American English. If in doubt, consult the [Merriam-Webster dictionary](https://www.merriam-webster.com/).
|
||||
|
||||
Follow the [Supabase documentation word list](./WORD_LIST.md) for preferred spelling, capitalization, and usage. No tool checks terminology, so check your own prose against the list, or let `/edit-the-docs` do it.
|
||||
|
||||
## Search
|
||||
|
||||
Search uses a Supabase instance. During CI, [a script](https://github.com/supabase/supabase/blob/master/apps/docs/scripts/search/generate-embeddings.ts) collects guides, reference documentation, and other content. The script creates OpenAI embeddings and stores the search index in a Supabase database.
|
||||
|
||||
@@ -57,4 +57,4 @@ for coverage and skipped rules.
|
||||
|
||||
## Contributing
|
||||
|
||||
For repo organization and style guide, see the [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md). If you write with an AI coding agent, use the `/write-the-docs` skill to draft, `/edit-the-docs` to revise an existing page, and `/review-the-docs` to self-review before you open a PR.
|
||||
For how to write a page, see the [style guide](https://github.com/supabase/supabase/tree/master/apps/docs/style-guide). For repo organization, see the [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md). If you write with an AI coding agent, use the `/write-the-docs` skill to draft, `/edit-the-docs` to revise an existing page, and `/review-the-docs` to self-review before you open a PR.
|
||||
+1
-1
@@ -20,4 +20,4 @@ It also means that we can switch to any documentation system we want. On this si
|
||||
|
||||
## Contributing
|
||||
|
||||
To contribute to docs, see the [developers' guide](https://github.com/supabase/supabase/blob/master/apps/docs/DEVELOPERS.md) and [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md). If you write with an AI coding agent, use the `/write-the-docs` skill to draft and `/edit-the-docs` to revise an existing page.
|
||||
To contribute to docs, see the [style guide](https://github.com/supabase/supabase/tree/master/apps/docs/style-guide) for how to write a page, and the [developers' guide](https://github.com/supabase/supabase/blob/master/apps/docs/DEVELOPERS.md) and [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md) for repo mechanics. If you write with an AI coding agent, use the `/write-the-docs` skill to draft and `/edit-the-docs` to revise an existing page.
|
||||
Reference in new issue
Block a user