Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

fix: Improve mermaid notation for markdown content and add contriburting instructions (#46679)

Jeremias Menichelli37357288cf13
diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.md
index f1fe7b92ba7..825c9e22150 100644
--- a/apps/docs/CONTRIBUTING.md
+++ b/apps/docs/CONTRIBUTING.md
@@ -211,6 +211,47 @@ Optionally highlight lines by using `mark=${lineNumber}`.
Don't use footnotes.
+### Graphs
+
+Render diagrams (flowcharts, sequence diagrams, entity-relationship diagrams, etc.) by writing a fenced code block with `mermaid` as the language. The MDX renderer routes these blocks through the shared `Mermaid` component, so theming follows light/dark mode automatically.
+
+For the full list of supported diagram types and their syntax, see the [official Mermaid diagram reference](https://mermaid.js.org/intro/syntax-reference.html).
+
+Sequence diagram:
+
+````mdx
+```mermaid
+sequenceDiagram
+ participant User
+ participant Browser
+ participant Supabase
+
+ User->>Browser: Clicks "Sign in"
+ Browser->>Supabase: Request authorization
+ Supabase->>Browser: Return token
+```
+````
+
+Flowchart (`flowchart` accepts a direction like `LR`, `TD`, etc.):
+
+````mdx
+```mermaid
+flowchart LR
+ A["content/**/*.md"] -->|Contentlayer| B[MDX]
+ B --> C[Rehype]
+ C -->|Our Plugin| D[SVG]
+ D -->|Base64| E[Embedded Images]
+```
+````
+
+A few tips:
+
+- Use the standard Mermaid diagram keywords (`sequenceDiagram`, `flowchart`, `erDiagram`, etc.) on the first line of the block.
+- Keep diagrams focused on a single flow or concept. If a diagram gets too dense, split it into multiple smaller diagrams.
+- Wrap node labels that contain special characters (`*`, `/`, spaces, punctuation) in double quotes, for example `A["content/**/*.md"]`.
+- Don't hardcode colors. The component themes the diagram automatically so it matches both light and dark mode.
+- Use diagrams to support the prose, not replace it. Explain the key takeaway in text near the diagram.
+
### Images
Images are uploaded in the `apps/docs/public/img` folder.
diff --git a/apps/docs/content/guides/integrations/partner-integration-guide.mdx b/apps/docs/content/guides/integrations/partner-integration-guide.mdx
index 44cc2915556..74ff3e28eeb 100644
--- a/apps/docs/content/guides/integrations/partner-integration-guide.mdx
+++ b/apps/docs/content/guides/integrations/partner-integration-guide.mdx
@@ -18,43 +18,42 @@ Pick the method that fits your security requirements, then follow the matching s
In this method, you implement a single `GET` endpoint. Supabase redirects the user to this endpoint when they click **Install Integration**, and your endpoint kicks off the OAuth flow.
-<Mermaid
- chart={`sequenceDiagram
- autonumber
- participant User
- participant Browser
- participant Partner as Partner (OAuth Client)
- participant Supabase as Supabase (OAuth Authorization Server/Protected Resource)
+```mermaid
+sequenceDiagram
+ autonumber
+ participant User
+ participant Browser
+ participant Partner as Partner (OAuth Client)
+ participant Supabase as Supabase (OAuth Authorization Server/Protected Resource)
- Note over Browser: Supabase Dashboard Open
+ Note over Browser: Supabase Dashboard Open
- User->>Browser: Clicks "Install Integration"
+ User->>Browser: Clicks "Install Integration"
- Browser->>Partner: "Connect to Partner" Click Handler Page
- Partner->>Browser: Redirect to Supabase Authorization Page
+ Browser->>Partner: "Connect to Partner" Click Handler Page
+ Partner->>Browser: Redirect to Supabase Authorization Page
- Browser->>Supabase: Request Authorization
- Supabase->>Browser: Redirect to Consent Screen
+ Browser->>Supabase: Request Authorization
+ Supabase->>Browser: Redirect to Consent Screen
- Browser->>User: Display Consent Screen
- User->>Browser: Gives Consent
+ Browser->>User: Display Consent Screen
+ User->>Browser: Gives Consent
- Browser->>Supabase: Submit User Consent
- Supabase->>Browser: Redirect to Partner With Authorization Code
+ Browser->>Supabase: Submit User Consent
+ Supabase->>Browser: Redirect to Partner With Authorization Code
- Browser->>Partner: Submit Authorization Code
+ Browser->>Partner: Submit Authorization Code
- Partner->>Supabase: Exchange Authorization Code for Token
- Supabase->>Partner: Return Token
+ Partner->>Supabase: Exchange Authorization Code for Token
+ Supabase->>Partner: Return Token
- Partner->>Supabase: Request Management API Resources
- Supabase->>Partner: Return Resources
+ Partner->>Supabase: Request Management API Resources
+ Supabase->>Partner: Return Resources
- Partner->>Browser: Ok 200, OAuth Flow Complete
+ Partner->>Browser: Ok 200, OAuth Flow Complete
- Browser->>User: Display "Integration Installed" Message`}
-
-/>
+ Browser->>User: Display "Integration Installed" Message
+```
### Step 1: Implement the redirect endpoint
@@ -88,55 +87,54 @@ You will implement two endpoints:
1. A `POST` endpoint that validates the signed JWT and returns a unique redirect URL.
2. A `GET` endpoint that handles the user once they are redirected to that URL.
-<Mermaid
- chart={`sequenceDiagram
- autonumber
- participant User
- participant Browser
- participant Partner as Partner (OAuth Client)
- participant Supabase as Supabase (OAuth Authorization Server/Protected Resource)
+```mermaid
+sequenceDiagram
+ autonumber
+ participant User
+ participant Browser
+ participant Partner as Partner (OAuth Client)
+ participant Supabase as Supabase (OAuth Authorization Server/Protected Resource)
- Note over Browser: Supabase Dashboard Open
+ Note over Browser: Supabase Dashboard Open
- User->>Browser: Clicks "Install Integration"
+ User->>Browser: Clicks "Install Integration"
- Browser->>Supabase: Request Redirect URL Generation
- Supabase->>Partner: Send Signed JWT
- Partner->>Partner: Validate JWT
- Partner->>Partner: Generate Unique Redirect URL
- Partner->>Supabase: Return Redirect URL
- Supabase->>Browser: Redirect to the Redirect URL
+ Browser->>Supabase: Request Redirect URL Generation
+ Supabase->>Partner: Send Signed JWT
+ Partner->>Partner: Validate JWT
+ Partner->>Partner: Generate Unique Redirect URL
+ Partner->>Supabase: Return Redirect URL
+ Supabase->>Browser: Redirect to the Redirect URL
- Browser->>Partner: Visit Redirect URL
- Partner->>Partner: Validate Redirect Record
- Partner->>Browser: Optional User Actions
- Browser->>User: User Performs Optional Actions
- User->>Browser: User Optional Actions Complete
- Browser->>Partner: User Optional Actions Complete
- Partner->>Browser: Redirect to Supabase Authorization Page
+ Browser->>Partner: Visit Redirect URL
+ Partner->>Partner: Validate Redirect Record
+ Partner->>Browser: Optional User Actions
+ Browser->>User: User Performs Optional Actions
+ User->>Browser: User Optional Actions Complete
+ Browser->>Partner: User Optional Actions Complete
+ Partner->>Browser: Redirect to Supabase Authorization Page
- Browser->>Supabase: Request Authorization
- Supabase->>Browser: Redirect to Consent Screen
+ Browser->>Supabase: Request Authorization
+ Supabase->>Browser: Redirect to Consent Screen
- Browser->>User: Display Consent Screen
- User->>Browser: Gives Consent
+ Browser->>User: Display Consent Screen
+ User->>Browser: Gives Consent
- Browser->>Supabase: Submit User Consent
- Supabase->>Browser: Redirect to Partner With Authorization Code
+ Browser->>Supabase: Submit User Consent
+ Supabase->>Browser: Redirect to Partner With Authorization Code
- Browser->>Partner: Submit Authorization Code
+ Browser->>Partner: Submit Authorization Code
- Partner->>Supabase: Exchange Authorization Code for Token
- Supabase->>Partner: Return Token
+ Partner->>Supabase: Exchange Authorization Code for Token
+ Supabase->>Partner: Return Token
- Partner->>Supabase: Request Management API Resources
- Supabase->>Partner: Return Resources
+ Partner->>Supabase: Request Management API Resources
+ Supabase->>Partner: Return Resources
- Partner->>Browser: Ok 200, OAuth Flow Complete
+ Partner->>Browser: Ok 200, OAuth Flow Complete
- Browser->>User: Display "Integration Installed" Message`}
-
-/>
+ Browser->>User: Display "Integration Installed" Message
+```
### Step 1: Exchange public keys with Supabase
diff --git a/apps/docs/features/docs/MdxBase.shared.tsx b/apps/docs/features/docs/MdxBase.shared.tsx
index ed70fab6657..134ffc1ed31 100644
--- a/apps/docs/features/docs/MdxBase.shared.tsx
+++ b/apps/docs/features/docs/MdxBase.shared.tsx
@@ -42,6 +42,22 @@ const AdmonitionWithMargin = (props: AdmonitionProps) => {
return <Admonition {...props} className="mb-8" />
}
+/**
+ * Route fenced ```mermaid blocks through the Mermaid component; everything else
+ * continues through `CodeBlock` for syntax highlighting.
+ */
+const Pre = (props: any) => {
+ const child = Array.isArray(props.children) ? props.children[0] : props.children
+ const className: unknown = child?.props?.className
+ if (typeof className === 'string' && className.split(' ').includes('language-mermaid')) {
+ const code = child.props.children
+ if (typeof code === 'string') {
+ return <Mermaid chart={code.trim()} />
+ }
+ }
+ return <CodeBlock {...props} />
+}
+
const components = {
Accordion,
AccordionItem,
@@ -99,7 +115,7 @@ const components = {
{props.children}
</Heading>
),
- pre: CodeBlock,
+ pre: Pre,
/**
* Force inline code tags to go sync, this prevents Heading anchor resolution fail due to
* our CodeBlock component being async. We need to find a better solution for more future