mirror of
https://github.com/supabase/supabase.git
synced 2026-07-07 07:30:21 +08:00
837e314088
Add a contributing guide to docs, which links to resources for contributors and includes examples of usable components when writing docs content.
400 lines
8.4 KiB
Plaintext
400 lines
8.4 KiB
Plaintext
# 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
|
|
<Accordion
|
|
type="default"
|
|
openBehaviour="multiple"
|
|
chevronAlign="right"
|
|
justified
|
|
size="medium"
|
|
className="text-foreground-light mt-8 mb-6"
|
|
>
|
|
<div className="border-b mt-3 pb-3">
|
|
<AccordionItem
|
|
header="Accordion item 1"
|
|
id="item-1"
|
|
>
|
|
|
|
Your content here.
|
|
|
|
</AccordionItem>
|
|
|
|
</div>
|
|
<div className="border-b mt-3 pb-3">
|
|
<AccordionItem
|
|
header="Accordion item 2"
|
|
id="item-2"
|
|
>
|
|
|
|
More content here.
|
|
|
|
</AccordionItem>
|
|
|
|
</div>
|
|
</Accordion>
|
|
```
|
|
|
|
<Accordion
|
|
type="default"
|
|
openBehaviour="multiple"
|
|
chevronAlign="right"
|
|
justified
|
|
size="medium"
|
|
className="text-foreground-light mt-8 mb-6"
|
|
>
|
|
<div className="border-b mt-3 pb-3">
|
|
<AccordionItem
|
|
header="Accordion item 1"
|
|
id="item-1"
|
|
>
|
|
|
|
Your content here.
|
|
|
|
</AccordionItem>
|
|
|
|
</div>
|
|
<div className="border-b mt-3 pb-3">
|
|
<AccordionItem
|
|
header="Accordion item 2"
|
|
id="item-2"
|
|
>
|
|
|
|
More content here.
|
|
|
|
</AccordionItem>
|
|
|
|
</div>
|
|
</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.
|
|
|
|
```mdx
|
|
<Admonition type="danger">
|
|
|
|
This could lead to data loss!
|
|
|
|
</Admonition>
|
|
|
|
<Admonition type="deprecation">
|
|
|
|
This feature is deprecated.
|
|
|
|
</Admonition>
|
|
|
|
<Admonition type="caution">
|
|
|
|
You should make sure you don't set this up wrong.
|
|
|
|
</Admonition>
|
|
|
|
<Admonition type="tip">
|
|
|
|
In certain cases, you may want to do this.
|
|
|
|
</Admonition>
|
|
|
|
<Admonition type="note">
|
|
|
|
Additional helpful information.
|
|
|
|
</Admonition>
|
|
```
|
|
|
|
<Admonition type="danger">
|
|
|
|
This could lead to data loss!
|
|
|
|
</Admonition>
|
|
|
|
<Admonition type="deprecation">
|
|
|
|
This feature is deprecated.
|
|
|
|
</Admonition>
|
|
|
|
<Admonition type="caution">
|
|
|
|
You should make sure you don't set this up wrong.
|
|
|
|
</Admonition>
|
|
|
|
<Admonition type="tip">
|
|
|
|
In certain cases, you may want to do this.
|
|
|
|
</Admonition>
|
|
|
|
<Admonition type="note">
|
|
|
|
Additional helpful information.
|
|
|
|
</Admonition>
|
|
|
|
### Icons
|
|
|
|
The following icons are available. They can be styled with [Tailwind](https://tailwindcss.com/) classes:
|
|
|
|
```mdx
|
|
<IconArrowDown />
|
|
<IconCheck />
|
|
<IconX />
|
|
```
|
|
|
|
<div class="flex items-center gap-2">
|
|
<IconArrowDown />
|
|
<IconCheck />
|
|
<IconX />
|
|
</div>
|
|
|
|
### 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
|
|
<Image
|
|
alt="Supabase architectural diagram"
|
|
src={{
|
|
dark: '/docs/img/supabase-architecture.svg',
|
|
light: '/docs/img/supabase-architecture--light.svg',
|
|
}}
|
|
zoomable
|
|
/>
|
|
```
|
|
|
|
<Image
|
|
alt="Supabase architectural diagram"
|
|
src={{
|
|
dark: '/docs/img/supabase-architecture.svg',
|
|
light: '/docs/img/supabase-architecture--light.svg',
|
|
}}
|
|
zoomable
|
|
/>
|
|
|
|
### 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
|
|
<ProjectConfigVariables variable="url" />
|
|
<ProjectConfigVariables variable="anonKey" />
|
|
```
|
|
|
|
<ProjectConfigVariables variable="url" />
|
|
<ProjectConfigVariables variable="anonKey" />
|
|
|
|
### Step Hike
|
|
|
|
For tutorials, which feature step-by-step instructions, often with accompanying code, we use the `StepHike` pattern:
|
|
|
|
````mdx
|
|
<StepHikeCompact>
|
|
|
|
<StepHikeCompact.Step step={1}>
|
|
|
|
<StepHikeCompact.Details title="The first step">
|
|
|
|
Explanation of what to do first.
|
|
|
|
</StepHikeCompact.Details>
|
|
|
|
<StepHikeCompact.Code>
|
|
|
|
```sql
|
|
select ...
|
|
```
|
|
|
|
</StepHikeCompact.Code>
|
|
|
|
</StepHikeCompact.Step>
|
|
|
|
<StepHikeCompact.Step step={2}>
|
|
|
|
<StepHikeCompact.Details title="No code in this step" fullWidth>
|
|
|
|
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.
|
|
|
|
</StepHikeCompact.Details>
|
|
|
|
</StepHikeCompact.Step>
|
|
|
|
</StepHikeCompact>
|
|
````
|
|
|
|
<StepHikeCompact>
|
|
|
|
<StepHikeCompact.Step step={1}>
|
|
|
|
<StepHikeCompact.Details title="The first step">
|
|
|
|
Explanation of what to do first.
|
|
|
|
</StepHikeCompact.Details>
|
|
|
|
<StepHikeCompact.Code>
|
|
|
|
```sql
|
|
select ...
|
|
```
|
|
|
|
</StepHikeCompact.Code>
|
|
|
|
</StepHikeCompact.Step>
|
|
|
|
<StepHikeCompact.Step step={2}>
|
|
|
|
<StepHikeCompact.Details title="No code in this step" fullWidth>
|
|
|
|
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.
|
|
|
|
|
|
</StepHikeCompact.Details>
|
|
|
|
</StepHikeCompact.Step>
|
|
|
|
</StepHikeCompact>
|
|
|
|
### 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
|
|
<Tabs
|
|
scrollable
|
|
size="small"
|
|
type="underlined"
|
|
defaultActiveId="js"
|
|
queryGroup="language"
|
|
>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```js
|
|
const supabase = createSupabaseClient()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="dart" label="Dart">
|
|
|
|
```dart
|
|
void main() async {
|
|
Supabase.initialize();
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
````
|
|
|
|
<Tabs
|
|
scrollable
|
|
size="small"
|
|
type="underlined"
|
|
defaultActiveId="js"
|
|
queryGroup="language"
|
|
>
|
|
<TabPanel id="js" label="JavaScript">
|
|
|
|
```js
|
|
const supabase = createSupabaseClient()
|
|
```
|
|
|
|
</TabPanel>
|
|
<TabPanel id="dart" label="Dart">
|
|
|
|
```dart
|
|
void main() async {
|
|
Supabase.initialize();
|
|
}
|
|
```
|
|
|
|
</TabPanel>
|
|
</Tabs>
|
|
|
|
## 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:
|
|
|
|
<Accordion
|
|
type="default"
|
|
openBehaviour="multiple"
|
|
chevronAlign="right"
|
|
justified
|
|
size="medium"
|
|
className="text-foreground-light mt-8 mb-6"
|
|
>
|
|
<div className="border-b mt-3 pb-3">
|
|
<AccordionItem
|
|
header="Database setup"
|
|
id="database-setup"
|
|
>
|
|
|
|
```mdx
|
|
<DatabaseSetup />
|
|
```
|
|
|
|
<DatabaseSetup />
|
|
|
|
</AccordionItem>
|
|
|
|
</div>
|
|
<div className="border-b mt-3 pb-3">
|
|
<AccordionItem
|
|
header="Create client for Auth"
|
|
id="create-client-auth"
|
|
>
|
|
|
|
```mdx
|
|
<CreateClientSnippet />
|
|
```
|
|
|
|
<CreateClientSnippet />
|
|
|
|
</AccordionItem>
|
|
|
|
</div>
|
|
</Accordion>
|
|
|
|
To make a new partial:
|
|
|
|
1. Make a new MDX file in `apps/docs/components/MDX`.
|
|
1. Write your reusable content.
|
|
1. Inside `apps/docs/components/MDX/partials.tsx`, import and re-export your partial.
|
|
1. Inside `apps/docs/features/docs/mdx.shared.tsx`, import your partial and include it in the `components` object.
|
|
1. You can now use your partial inside any other MDX file by using: `<YourPartialName />`.
|