supabase/apps/docs/CONTRIBUTING.md

Contributing to Supabase docs

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.

General principles

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 use we to refer to the reader. Use we only to refer to the Supabase team.

Document types

Supabase docs contain 4 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

They shouldn'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 (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

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.

Reference

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

Repo organization

Most docs pages are contained in the apps/docs/pages 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'

File structure

The Supabase docs use MDX.

Adding a new doc requires:

• A layout
• Metadata
• A page export
• A navigation entry (in a separate file)

// required import
import Layout from '~/layouts/DefaultGuideLayout'


/*
 * required metadata fields
 * title: required - page title
 * description: required - page description
 *
 * optional metadata fields
 * id: optional - not currently being used 
 * subtitle: optional - displayed below the title
 * sidebar_label: optional - if you want the sidebar text to be different from the title
 * hide_table_of_contents: optional - hides the table of contents on the right side
 * tocVideo: optional - a YouTube slug, displays the video above the table of contents
 */
export const meta = {
  id: 'nextjs-server-components',
  title: 'Supabase Auth with Next.js Server Components',
  description:
    'Authentication helpers for creating an authenticated Supabase client in Next.js 13 app directory Server Components.',
  sidebar_label: 'Next.js Server Components',
}

// content
You can use **Markdown syntax**.

// required export
export const Page = ({ children }) => <Layout meta={meta} children={children} />

export default Page

The navigation is defined in NavigationMenu.constants.ts.

Add an entry with the name, url, and (optional) icon for your page.

Content reuse

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.

Components and elements

Docs include normal Markdown elements such as lists, and custom components such as admonitions (callouts).

Here are some guidelines for using elements:

Admonitions

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 leaks
• deprecation to notify the user about features that are (or will soon be) deprecated
• caution to warn about anything that could cause a bug or serious user inconvenience
• tip to point out helpful but optional actions
• note for anything else

<Admonition type="note" label="Optional label displays as title">

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 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 running npm run format, or by setting up auto-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 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

Footnotes

Don't use footnotes.

Images

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.

Links

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).

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.

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

Videos

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 metadata:

export const meta = {
  ...
  tocVideo: 'rzglqRdZUQE',
}

Styling, formatting, and grammar

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 than Set 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 than realtime, database and authentication.
• 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.

Here are some exceptions and Supabase-specific guidelines.

General word usage

• 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 clicked.
  • Checkboxes are selected.
  • Toggles are enabled and disabled.
  • Labels of UI elements are bolded. For example, Click **Confirm**.

Word list

• Backend isn't hyphenated (not back-end).
• Frontend isn't hyphenated (not front-end).
• Login is a noun. Log in is a verb.
• Postgres is capitalized, except in code, and used instead of PostgreSQL.
• Setup is a noun. Set up is a verb.
• Supabase is capitalized (not supabase), except in code.
• Supabase Platform is in title case (not Supabase platform).