# 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](https://github.com/supabase/supabase), under the `apps/docs` directory.
In the repo, you'll also find:
- The [developers guide](https://github.com/supabase/supabase/blob/master/apps/docs/DEVELOPERS.md), which will help you set up your local machine to develop the docs site
- The [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md), 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:
```mdx
```
### 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.
```mdx
This could lead to data loss!
This feature is deprecated.
You should make sure you don't set this up wrong.
In certain cases, you may want to do this.
Additional helpful information.
```
This could lead to data loss!
This feature is deprecated.
You should make sure you don't set this up wrong.
In certain cases, you may want to do this.
Additional helpful information.
### Code Samples
You can include code samples as normal in Markdown. Name is optional:
````mdx
```js name=file.js
const PI = 3.14
```
````
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:
{/* prettier-ignore */}
```mdx
<$CodeSample
path="/relative/path/from/examples/directory.js"
{/* Array of [start, end] line numbers to include.
Line numbers are 1-indexed and inclusive.
-1 indicates the final line. */}
lines={[[1, 3], [5, -1]]}
{/* Optional, displays as a file name on the code block */}
meta="name=display/path.js"
{/* Optional, strips TypeScript types to produce JavaScript, which you also include with another */}
convertToJs={true}
/>
```
If the file is within some other GitHub repo:
```mdx
<$CodeSample
external={true}
org="supabase"
repo="cli"
commit="1623aa9b95ec90e21c5bae5a0d50dcf272abe92f"
path="/relative/path/from/root.js"
lines={[[1, 3], [5, -1]]}
meta="name=display/path.js"
convertToJs={true}
/>
```
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:
```mdx
<$CodeSample
path="/path/to/typescript-file.ts"
lines={[[1, -1]]}
convertToJs={true}
/>
```
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:
````mdx
<$CodeTabs>
```js name=a.js
console.log('Hello, world!')
```
```js name=b.js
console.log('Goodbye, world!')
```
````
This produces:
<$CodeTabs>
```js name=a.js
console.log('Hello, world!')
```
```js name=b.js
console.log('Goodbye, world!')
```
#### TypeScript type hints
JavaScript and TypeScript code blocks include type hints:
````mdx
```js
let hello = 'Hello, world!'
```
````
Hover over `hello` to see the hint.
```js
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:
````mdx
```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('dummy', 'client')
// ---cut---
const result = supabase.auth.signInWithPassword({
email: 'test@example.com',
password: 'test1234',
})
```
````
Note the hidden statements above the cut. Hover over `signInWithPassword` to see the hint:
```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('dummy', 'client')
// ---cut---
const result = supabase.auth.signInWithPassword({
email: 'test@example.com',
password: 'test1234',
})
```
### Icons
The following icons are available. They can be styled with [Tailwind](https://tailwindcss.com/) classes:
```mdx
```
### Image
You can include images with regular Markdown syntax:
```mdx
```
If your image has alternate light and dark versions, or you want to make it zoomable, you can also use the image component:
```mdx
```
### 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:
```mdx
```
### Step Hike
For tutorials, which feature step-by-step instructions, often with accompanying code, we use the `StepHike` pattern:
````mdx
Explanation of what to do first.
```sql
select ...
```
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.
````
Explanation of what to do first.
```sql
select ...
```
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.
### 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.
````mdx
```js
const supabase = createSupabaseClient()
```
```dart
void main() async {
Supabase.initialize();
}
```
````
```js
const supabase = createSupabaseClient()
```
```dart
void main() async {
Supabase.initialize();
}
```
### Info Tooltip
The InfoTooltip component is used to add more context to a word or phrase via tooltip.
```mdx
Supabase
```
## 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:
```mdx
<$Partial path="database_setup.mdx" />
```
<$Partial path="database_setup.mdx" />
```mdx
<$Partial path="create_client_snippet.mdx" />
```
<$Partial path="create_client_snippet.mdx" />
To make a new partial:
1. Make a new MDX file in `apps/docs/content/_partials`.
1. Write your reusable content.
1. 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.
```mdx
<$Partial path="path/to/file.mdx" variables={{ "substitute": "this" }}>
```
```mdx
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.