Our docs help developers to get started and keep succeeding with Supabase. We welcome contributions from everyone.
If you'd like to contribute, see our list of recommended issues. 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.
Docs should be helpful, quick to read, and easy to understand. We have an audience of global readers who speak different native languages.
To make docs as clear as possible:
- 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. 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.
- Each paragraph should have one topic only. Start a new paragraph whenever you change the topic. 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 usewe
to refer to the reader. Usewe
only to refer to the Supabase team.
Supabase docs contain 4 types of documents. Before you start writing, think about what type of doc you need.
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
They shouldn't include:
- Instructions on how to use it
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 (lists of steps for the reader to follow). They provide context for why certain instructions are given.
For inspiration, see an example of a tutorial.
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. Think of an instruction manual for building a desk: it's a list of concise steps that the user can go through quickly.
For inspiration, see an example of a guide.
References are factual and to the point. Think of dictionary entries.
They should include:
- Function parameters
- Return types
- Code samples
- Warnings for critical errors (for example, missteps that can cause data loss)
They shouldn't include:
- Explanations of the context for a feature
- Examples of use cases
- Multi-step instructions
Most docs pages are contained in the apps/docs/content
directory. Some docs sections are federated from other repositories, for example pg_graphql
. Reference docs are generated from spec files in the spec
directory.
You can usually identify a federated or reference doc because it uses a Next.js dynamic route (for example, [[...slug]].tsx
). Look for the spec file import or the repo definition to find the content location.
Example spec file import:
import specFile from '~/spec/transforms/analytics_v0_openapi_deparsed.json' assert { type: 'json' }
Example repo definition:
const org = 'supabase'
const repo = 'pg_graphql'
const branch = 'master'
const docsDir = 'docs'
const externalSite = 'https://supabase.github.io/pg_graphql'
Check the sections for guide structure and reference structure to learn more about the file structures.
The Supabase docs use MDX. Guides are written in unstructured prose as MDX documents.
Adding a new guide requires:
- YAML frontmatter
- A navigation entry (in a separate file)
Frontmatter looks like this. title
is mandatory. There are also optional properties that you can use to control the page display, including subtitle
, tocVideo
, and hideToc
.
---
title: How to connect to Supabase
hideToc: true
---
The navigation is defined in NavigationMenu.constants.ts
.
Add an entry with the name
, url
, and (optional) icon
for your page.
Reference docs are produced from the reference specs and library source code. A common spec file contains shared function and endpoint definitions, and library-specific spec files contain further details.
Each type of library (for example, language SDK or CLI) has a common spec file. For example, see the spec file for the language SDKs. This file contains definitions for the common SDK functions:
- id - Identifies the function
- title - Human-readable title
- slug - URL slug
- product - Supabase product that owns the function. For example, database operations are owned by
database
, and auth functions are owned byauth
- type -
function
for a structured function definition ormarkdown
for a prose explainer section.
To add a new function, manually add an entry to this common file.
Each library also has its own spec file containing library-specific details. For example, see the JavaScript SDK spec file.
The functions listed in this file match the ones defined in the common spec file.
Each function contains a description, code examples, and optional notes. The parameters are pulled from the source code via the $ref
property, which references a function definition in the source code repo. These references are pulled down and transformed using commands in the spec Makefile. Unless you're a library maintainer, you don't need to worry about this.
If you're a library maintainer, follow these steps when updating function parameters or return values:
- Get your changes merged to
master
in your library - This will kick off an action that automatically updates the spec file in the library's
gh-pages
branch - Run
make
in/spec
of thesupabase/supabase
repo. This will regenerate all of thetsdoc
files that the docs site uses - You should now see the changes you've made in the docs site locally
If you copy the same content multiple times across different files, create a partial for content reuse instead. Partials are MDX files contained in apps/docs/components/MDX
. They contain reusable snippets that can be inserted in multiple pages. For example, you can create a partial to define a common setup step for a group of tutorials.
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/components/index.tsx
.
Docs include normal Markdown elements such as lists, and custom components such as admonitions (callouts).
Here are some guidelines for using elements:
Admonitions (or callouts) draw reader attention to an important point or an aside. They highlight important information, but get less effective if they're overused.
Use admonitions sparingly. Don't stack them on top of each other.
Choose the appropriate type
for your admonition:
danger
to warn the user about any missteps that could cause data loss or data leaksdeprecation
to notify the user about features that are (or will soon be) deprecatedcaution
to warn about anything that could cause a bug or serious user inconveniencetip
to point out helpful but optional actionsnote
for anything else
<Admonition type="note" label="Optional label displays as title">
Your content here
</Admonition>
Don't use blockquotes.
Keep code lines short to avoid scrolling. For example, you can split long shell commands with \
.
-
JavaScript/TypeScript
The
supabase
repo uses Prettier, which also formats JS/TS in code blocks. Your PR is blocked from merging if the Prettier check fails. Ensure that your code blocks are formatted by runningnpm run format
, or by setting up auto-formatting in your IDE. -
SQL
Prefer lowercase for SQL. For example,
select * from table
rather thanSELECT * FROM table
.
Optionally specify a filename for the codeblock by including it after the opening backticks and language specifier:
```ts environment.ts
Optionally highlight lines by using mark=${lineNumber}
.
```js mark=12:13
Don't use footnotes.
Images are uploaded in the apps/docs/public/img
folder.
For vector illustrations, use svg
. For screenshots and non-vector graphics, use png
. (These are automatically converted to webp
for supported browsers.)
Redact any sensitive information, such as API keys.
Link text should be descriptive. The reader should understand where the link goes from reading the link text alone. This is important for accessibility. For example, don't use here
as link text.
But link text shouldn't be too long. 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)
.
Use relative links when linking within the supabase.com
domain. For example, [link to another page in Supabase docs](/docs/guides/getting-started)
.
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.
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
Use tabs to provide alternative instructions for different platforms or languages.
The queryGroup
param is optional. It lets you link directly to a tab by using the query group as a query param in the URL, for example: https://supabase.com/docs/my-page?packagemanager=ts
<Tabs
scrollable
size="small"
type="underlined"
defaultActiveId="npm"
queryGroup="packagemanager"
>
<TabPanel id="npm" label="npm">
// ...
</TabPanel>
<TabPanel id="yarn" label="Yarn">
// ...
</TabPanel>
</Tabs>
Include videos as TOC (Table of Contents) videos rather than putting them in the main text.
You can define a TOC video in the page frontmatter:
---
tocVideo: 'rzglqRdZUQE',
---
Don't worry too much about grammar rules. Grammar is useful if, and only if, it makes your writing clearer. For example, you can use sentence fragments if they're self-explanatory.
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 thanSet Up Authentication
. - Use the Oxford comma (a comma before the
and
that marks the last item in a list). For example,realtime, database, and authentication
rather thanrealtime, database and authentication
. - Use the present tense as much as possible. For example,
the AI assistant answers your question
rather thanthe AI assistant will answer your question
.
Use American English. If in doubt, consult the Merriam-Webster dictionary.
Here are some exceptions and Supabase-specific guidelines.
- Filler words: You can often make your writing more concise by removing these words. (Some of these words can also sound patronizing.)
- Actually
- Easy, easily
- Just
- Let's
- Please
- Simple, simply
- UI elements
- Buttons are
click
ed. - Checkboxes are
select
ed. - Toggles are
enable
d anddisable
d. - Labels of UI elements are bolded. For example,
Click **Confirm**.
- Buttons are
Backend
isn't hyphenated (notback-end
).Frontend
isn't hyphenated (notfront-end
).Login
is a noun.Log in
is a verb.Postgres
is capitalized, except in code, and used instead ofPostgreSQL
.Setup
is a noun.Set up
is a verb.Supabase
is capitalized (notsupabase
), except in code.Supabase Platform
is in title case (notSupabase platform
).
Search is handled using a Supabase instance. During CI, a script aggregates all content sources (eg. guides, reference docs, etc), indexes them using OpenAI embeddings, and stores them in a Supabase database.
Search uses a hybrid of native Postgres FTS and embedding similarity search based on pgvector
. At runtime, a PostgREST call triggers the RPC that runs the weighted FTS search, and an Edge Function is executed to perform the embedding search.