Contributing to Supabase Docs

Thanks for contributing to Supabase Docs! Here are a few resources to help you get started.

The code and content for our docs site are located in the main Supabase GitHub repo, under the apps/docs directory.

In the repo, you'll also find:

• The developers guide, which will help you set up your local machine to develop the docs site
• The contributing guide, which goes over the content organization and some general guidelines for writing docs content

Components#

Our docs content is mainly written in MDX. Aside from standard GitHub-flavored Markdown, you can use the following helper components to help you organize and display your content:

Accordion#

For content that requires progressive disclosure:

1
<Accordion
2
  type="default"
3
  openBehaviour="multiple"
4
  chevronAlign="right"
5
  justified
6
  size="medium"
7
  className="text-foreground-light mt-8 mb-6"
8
>
9
  <div className="border-b mt-3 pb-3">
10
    <AccordionItem
11
      header="Accordion item 1"
12
      id="item-1"
13
    >
14
15
    Your content here.
16
17
    </AccordionItem>
18
19
  </div>
20
  <div className="border-b mt-3 pb-3">
21
    <AccordionItem
22
      header="Accordion item 2"
23
      id="item-2"
24
    >
25
26
    More content here.
27
28
    </AccordionItem>
29
30
  </div>
31
</Accordion>

Admonition#

For extra information that doesn't fit into the main flow. There are 5 supported types of admonitions:

• 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

Leave a blank line between the admonition tag and the contained content. This will prevent Prettier from trying to break the lines within the content.

1
<Admonition type="danger">
2
3
This could lead to data loss!
4
5
</Admonition>
6
7
<Admonition type="deprecation">
8
9
This feature is deprecated.
10
11
</Admonition>
12
13
<Admonition type="caution">
14
15
You should make sure you don't set this up wrong.
16
17
</Admonition>
18
19
<Admonition type="tip">
20
21
In certain cases, you may want to do this.
22
23
</Admonition>
24
25
<Admonition type="note">
26
27
Additional helpful information.
28
29
</Admonition>

Code Samples#

You can include code samples as normal in Markdown. Name is optional:

1
```js name=file.js
2
const PI = 3.14
3
```

Or, you can use the <$CodeSample /> component to include code samples from a source code file.

If the file is within the supabase/supabase repo's examples directory:

1
<$CodeSample
2
path="/relative/path/from/examples/directory.js"
3
{/* Array of [start, end] line numbers to include.
4
Line numbers are 1-indexed and inclusive.
5
-1 indicates the final line. */}
6
lines={[[1, 3], [5, -1]]}
7
{/* Optional, displays as a file name on the code block */}
8
meta="name=display/path.js"
9
{/* Optional, strips TypeScript types to produce JavaScript, which you also include with another <CodeSample /> */}
10
convertToJs={true}
11
/>

If the file is within some other GitHub repo:

1
<$CodeSample
2
external={true}
3
org="supabase"
4
repo="cli"
5
commit="1623aa9b95ec90e21c5bae5a0d50dcf272abe92f"
6
path="/relative/path/from/root.js"
7
lines={[[1, 3], [5, -1]]}
8
meta="name=display/path.js"
9
convertToJs={true}
10
/>

The repo must be public, the org must be on the allow list, and the commit must be an immutable SHA (not a mutable tag or branch name).

Converting TypeScript to JavaScript#

You can automatically strip TypeScript types from code samples to produce JavaScript using the convertToJs option:

1
<$CodeSample
2
path="/path/to/typescript-file.ts"
3
lines={[[1, -1]]}
4
convertToJs={true}
5
/>

This is useful when you want to show JavaScript examples from TypeScript source files. The conversion:

• Removes all TypeScript type annotations, interfaces, and type definitions
• Converts the language identifier from typescript to javascript (or tsx to jsx)
• Happens before any line selection or elision processing
• Defaults to false to preserve TypeScript code when not specified

Multi-file code samples#

Multi-file code samples use the <$CodeTabs> annotation:

1
<$CodeTabs>
2
3
```js name=a.js
4
console.log('Hello, world!')
5
```
6
7
```js name=b.js
8
console.log('Goodbye, world!')
9
```
10
11
</$CodeTabs>

This produces:

1
console.log('Hello, world!')

TypeScript type hints#

JavaScript and TypeScript code blocks include type hints:

1
```js
2
let hello = 'Hello, world!'
3
```

Hover over hello to see the hint.

1
let hello = 'Hello, world!'

The entire code block must be a valid compilation target for TypeScript. That is, if you have undefined variables or missing imports, type hints won't be shown. You can add extra statements above the cut for variable definitions, etc.

You can also import the supabase-js library here:

1
```js
2
import { createClient } from '@supabase/supabase-js'
3
const supabase = createClient('dummy', 'client')
4
5
// ---cut---
6
const result = supabase.auth.signInWithPassword({
7
  email: 'test@example.com',
8
  password: 'test1234',
9
})
10
```

Note the hidden statements above the cut. Hover over signInWithPassword to see the hint:

1
const result = supabase.auth.signInWithPassword({
2
  email: 'test@example.com',
3
  password: 'test1234',
4
})

Icons#

The following icons are available. They can be styled with Tailwind classes:

1
<IconArrowDown />
2
<IconCheck />
3
<IconX />

Image#

You can include images with regular Markdown syntax:

1
![Supabase architectural diagram](/docs/img/supabase-architecture.svg)

If your image has alternate light and dark versions, or you want to make it zoomable, you can also use the image component:

1
<Image
2
  alt="Supabase architectural diagram"
3
  src={{
4
    dark: '/docs/img/supabase-architecture.svg',
5
    light: '/docs/img/supabase-architecture--light.svg',
6
  }}
7
  zoomable
8
/>

Project Variables#

Some guides and tutorials will require that users copy their Supabase project URL and anon key. You can provide those inline if the user is signed in:

1
<ProjectConfigVariables variable="url" />
2
<ProjectConfigVariables variable="publishable" />
3
<ProjectConfigVariables variable="anon" />

Step Hike#

For tutorials, which feature step-by-step instructions, often with accompanying code, we use the StepHike pattern:

1
<StepHikeCompact>
2
3
  <StepHikeCompact.Step step={1}>
4
5
    <StepHikeCompact.Details title="The first step">
6
7
    Explanation of what to do first.
8
9
    </StepHikeCompact.Details>
10
11
    <StepHikeCompact.Code>
12
13
      ```sql
14
      select ...
15
      ```
16
17
    </StepHikeCompact.Code>
18
19
  </StepHikeCompact.Step>
20
21
  <StepHikeCompact.Step step={2}>
22
23
    <StepHikeCompact.Details title="No code in this step" fullWidth>
24
25
    Explanation of what to do next. This stretches the full width of the section: Sweet tiramisu apple biscuit candy cake. Orange ipsum muffin cookie cake biscuit. Orange muffin vanilla sweet sugar candy. Sprinkles jelly sweet orange candy cream.
26
27
    </StepHikeCompact.Details>
28
29
  </StepHikeCompact.Step>
30
31
</StepHikeCompact>

1
select ...

Tabs#

Use tabs when users can select between multiple versions of the content. For example, the content might differ based on language or package manager.

If you include the queryGroup prop, the user's selection will sync with other tab groups. Leave out this prop to omit this behavior.

1
<Tabs
2
  scrollable
3
  size="small"
4
  type="underlined"
5
  defaultActiveId="js"
6
  queryGroup="language"
7
>
8
<TabPanel id="js" label="JavaScript">
9
10
```js
11
const supabase = createSupabaseClient()
12
```
13
14
</TabPanel>
15
<TabPanel id="dart" label="Dart">
16
17
```dart
18
void main() async {
19
  Supabase.initialize();
20
}
21
```
22
23
</TabPanel>
24
</Tabs>

1
const supabase = createSupabaseClient()

Info Tooltip#

The InfoTooltip component is used to add more context to a word or phrase via tooltip.

1
<InfoTooltip tooltipContent="The Postgres Development Platform.">Supabase</InfoTooltip>

Partials#

We incorporate content reuse in the docs to avoid duplication. If you find yourself writing the same content over and over, you can put it in a partial instead. Here are some examples of commonly used partials:

To make a new partial:

1. Make a new MDX file in apps/docs/content/_partials.
2. Write your reusable content.
3. You can now use your partial inside any other MDX file by using: <$Partial path="path/from/_partials/directory.mdx" />.

If you need compile-time variable replacement, you can define variables that get replaced with strings.

1
<$Partial path="path/to/file.mdx" variables={{ "substitute": "this" }}>

1
Here is the partial text to {{ .substitute }}.

Only string replacements are possible at this time. For more complex use cases, consider making a custom component.