Skip to content

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

[DOCS-1148] Improve prose for LLM readability (#47653)

Jeremias Menichelli5066261dbd4f
diff --git a/apps/docs/content/_partials/metrics_access.mdx b/apps/docs/content/_partials/metrics_access.mdx
index 94a3389207c..4f65008ed02 100644
--- a/apps/docs/content/_partials/metrics_access.mdx
+++ b/apps/docs/content/_partials/metrics_access.mdx
@@ -7,7 +7,7 @@ className="rounded-lg border border-foreground/10 bg-surface-100 text-foreground
>
<AccordionItem
- header={<span className="text-foreground font-medium">What you can do with the Metrics API</span>}
+ header="What you can do with the Metrics API"
id="how-do-i-check-when-a-user-went-through-mfa"
className="border-0 px-2 py-4"
>
diff --git a/apps/docs/content/guides/ai/concepts.mdx b/apps/docs/content/guides/ai/concepts.mdx
index 357581cc455..73f52fc93d6 100644
--- a/apps/docs/content/guides/ai/concepts.mdx
+++ b/apps/docs/content/guides/ai/concepts.mdx
@@ -41,7 +41,7 @@ Embeddings compress discrete information (words & symbols) into distributed cont
The chart below plots example phrases as points. Phrases with similar meanings sit close together, and unrelated phrases sit far apart.
-<img
+<Image
src="/docs/img/ai/vector-similarity.png"
alt="A two-dimensional chart plotting example phrases as points, where phrases with similar meanings sit close together and unrelated phrases sit far apart."
width="640"
diff --git a/apps/docs/content/guides/ai/hugging-face.mdx b/apps/docs/content/guides/ai/hugging-face.mdx
index 0fb7fd4cdfa..b5b0d4c4f90 100644
--- a/apps/docs/content/guides/ai/hugging-face.mdx
+++ b/apps/docs/content/guides/ai/hugging-face.mdx
@@ -149,7 +149,7 @@ curl --output result.jpg --location --request POST 'http://localhost:54321/funct
In this example, your generated image will save to `result.jpg`:
-<img
+<Image
src="/docs/img/ai/hugging-face/llama-sunglasses-example.png"
alt="Llama wearing sunglasses example"
width="400"
diff --git a/apps/docs/content/guides/auth/auth-mfa.mdx b/apps/docs/content/guides/auth/auth-mfa.mdx
index 8b68ced9293..e7e1744b5c1 100644
--- a/apps/docs/content/guides/auth/auth-mfa.mdx
+++ b/apps/docs/content/guides/auth/auth-mfa.mdx
@@ -307,7 +307,7 @@ If your application uses the Supabase Database, Storage or Edge Functions, Row L
>
<AccordionItem
-header={<span className="text-foreground">How do I check when a user went through MFA?</span>}
+header="How do I check when a user went through MFA?"
id="how-do-i-check-when-a-user-went-through-mfa"
>
diff --git a/apps/docs/content/guides/auth/server-side/creating-a-client.mdx b/apps/docs/content/guides/auth/server-side/creating-a-client.mdx
index 3dfe963a7e5..41dfa60552b 100644
--- a/apps/docs/content/guides/auth/server-side/creating-a-client.mdx
+++ b/apps/docs/content/guides/auth/server-side/creating-a-client.mdx
@@ -200,7 +200,7 @@ The Proxy is responsible for:
<Accordion>
<AccordionItem
- header={<span className="text-foreground">What does the `cookies` object do?</span>}
+ header="What does the `cookies` object do?"
id="utility-cookies"
>
@@ -213,7 +213,7 @@ The Proxy is responsible for:
</AccordionItem>
<AccordionItem
- header={<span className="text-foreground">Do I need to create a new client for every route?</span>}
+ header="Do I need to create a new client for every route?"
id="client-deduplication"
>
diff --git a/apps/docs/content/guides/local-development/cli/getting-started.mdx b/apps/docs/content/guides/local-development/cli/getting-started.mdx
index c6005edb3c6..10838693b14 100644
--- a/apps/docs/content/guides/local-development/cli/getting-started.mdx
+++ b/apps/docs/content/guides/local-development/cli/getting-started.mdx
@@ -58,7 +58,7 @@ and run one of the following:
- `sudo rpm -i <...>.rpm`
</TabPanel>
-<TabPanel id="npm" label="nodejs">
+<TabPanel id="npm" label="Node.js">
Run the CLI by prefixing each command with `npx` or `bunx`:
@@ -122,7 +122,7 @@ brew link --overwrite supabase-beta
Beta builds are attached to [GitHub pre-releases](https://github.com/supabase/cli/releases). Download the `.apk`, `.deb`, or `.rpm` for your platform and install with the same commands as [Linux packages](#linux-packages) above.
</TabPanel>
-<TabPanel id="npm" label="nodejs">
+<TabPanel id="npm" label="Node.js">
Install as a dev dependency:
@@ -199,7 +199,7 @@ brew upgrade supabase-beta
- `sudo rpm -i <...>.rpm`
</TabPanel>
-<TabPanel id="npm" label="nodejs">
+<TabPanel id="npm" label="Node.js">
If you have installed the CLI as dev dependency via [npm](https://www.npmjs.com/package/supabase), you can update it with:
diff --git a/apps/docs/content/guides/platform/migrating-to-supabase/auth0.mdx b/apps/docs/content/guides/platform/migrating-to-supabase/auth0.mdx
index 82f8d91462b..806660c54a5 100644
--- a/apps/docs/content/guides/platform/migrating-to-supabase/auth0.mdx
+++ b/apps/docs/content/guides/platform/migrating-to-supabase/auth0.mdx
@@ -80,6 +80,7 @@ Migrate existing users to Supabase Auth. This requires two main steps: first, ch
```ts
import { createClient } from '@supabase/supabase-js'
+
const supabase = createClient('your_project_url', 'your_supabase_api_key')
// ---cut---
@@ -100,6 +101,7 @@ Migrate existing users to Supabase Auth. This requires two main steps: first, ch
```ts
import { createClient } from '@supabase/supabase-js'
+
const supabase = createClient('your_project_url', 'your_supabase_api_key')
// ---cut---
@@ -122,6 +124,7 @@ For passwordless signin via email or phone, check for users with verified email
```ts
import { createClient } from '@supabase/supabase-js'
+
const supabase = createClient('your_project_url', 'your_supabase_api_key')
// ---cut---
@@ -162,6 +165,7 @@ Both columns are accessible from the admin user methods. To create a user with c
```ts
import { createClient } from '@supabase/supabase-js'
+
const supabase = createClient('your_project_url', 'your_supabase_api_key')
// ---cut---
@@ -205,7 +209,7 @@ create table private.user_metadata (
>
<AccordionItem
-header={<span className="text-foreground">I have IDs assigned to existing users in my database, how can I maintain these IDs?</span>}
+header="I have IDs assigned to existing users in my database, how can I maintain these IDs?"
id="custom-user-id"
>
@@ -228,7 +232,7 @@ const { data, error } = await supabase.auth.admin.createUser({
</AccordionItem>
<AccordionItem
-header={<span className="text-foreground">How can I allow my users to retain their existing password?</span>}
+header="How can I allow my users to retain their existing password?"
id="existing-password"
>
@@ -237,7 +241,7 @@ Supabase Auth never stores passwords as plaintext. Since Supabase Auth supports
</AccordionItem>
<AccordionItem
-header={<span className="text-foreground">My users have multi-factor authentication (MFA) enabled, how do I make sure they don't have to set up MFA again?</span>}
+header="My users have multi-factor authentication (MFA) enabled, how do I make sure they don't have to set up MFA again?"
id="mfa"
>
@@ -246,7 +250,7 @@ You can obtain an export of your users' MFA secrets by opening a support ticket
</AccordionItem>
<AccordionItem
-header={<span className="text-foreground">How do I migrate existing SAML Single Sign-On (SSO) connections?</span>}
+header="How do I migrate existing SAML Single Sign-On (SSO) connections?"
id="saml"
>
@@ -255,7 +259,7 @@ Customers may need to link their identity provider with Supabase Auth separately
</AccordionItem>
<AccordionItem
-header={<span className="text-foreground">How do I migrate my Auth0 organizations to Supabase?</span>}
+header="How do I migrate my Auth0 organizations to Supabase?"
id="migrate-org"
>
diff --git a/apps/docs/content/guides/storage/analytics/creating-analytics-buckets.mdx b/apps/docs/content/guides/storage/analytics/creating-analytics-buckets.mdx
index f9a6c7b1fe2..2680ec95879 100644
--- a/apps/docs/content/guides/storage/analytics/creating-analytics-buckets.mdx
+++ b/apps/docs/content/guides/storage/analytics/creating-analytics-buckets.mdx
@@ -72,7 +72,12 @@ print('Analytics bucket created:', response)
4. Select **Analytics Bucket** as the bucket type.
5. Click **Create**.
-<img alt="Create Analytics Bucket in Dashboard" src="/docs/img/storage/iceberg-bucket.png" />
+<Image
+ alt="Create Analytics Bucket in Dashboard"
+ width="644"
+ height="402"
+ src="/docs/img/storage/iceberg-bucket.png"
+/>
## Next steps
diff --git a/apps/docs/content/guides/storage/s3/authentication.mdx b/apps/docs/content/guides/storage/s3/authentication.mdx
index 879f3f11149..294e0b24c53 100644
--- a/apps/docs/content/guides/storage/s3/authentication.mdx
+++ b/apps/docs/content/guides/storage/s3/authentication.mdx
@@ -23,7 +23,12 @@ To authenticate with S3, generate a pair of credentials (Access Key ID and Secre
This is all the information you need to connect to Supabase Storage using any S3-compatible service.
-<img alt="Storage S3 Access keys" src="/docs/img/storage/s3-credentials.png" width="100%" />
+<Image
+ alt="Storage S3 Access keys"
+ src="/docs/img/storage/s3-credentials.png"
+ width="749"
+ height="490"
+/>
<Admonition type="note">
diff --git a/apps/docs/content/guides/telemetry/metrics.mdx b/apps/docs/content/guides/telemetry/metrics.mdx
index 4fd0dc73531..5ecbf90e80b 100644
--- a/apps/docs/content/guides/telemetry/metrics.mdx
+++ b/apps/docs/content/guides/telemetry/metrics.mdx
@@ -27,10 +27,11 @@ Pick the workflow that best matches your tooling. Cards link to Supabase-authore
<MetricsStackCards />
-<img
+<Image
src="/docs/img/guides/platform/supabase-grafana-prometheus.png"
alt="Supabase Grafana dashboard showcasing database metrics"
- className="mt-8 rounded-lg border border-foreground/10 shadow-xs"
+ width="3000"
+ height="1509"
/>
## Additional resources
diff --git a/apps/docs/content/guides/telemetry/metrics/grafana-cloud.mdx b/apps/docs/content/guides/telemetry/metrics/grafana-cloud.mdx
index a31a8e4b06e..39d96d066ba 100644
--- a/apps/docs/content/guides/telemetry/metrics/grafana-cloud.mdx
+++ b/apps/docs/content/guides/telemetry/metrics/grafana-cloud.mdx
@@ -44,10 +44,11 @@ If you prefer to reuse an existing Grafana Agent deployment, configure an [integ
This dashboard includes 200+ charts grouped by CPU, IO, connections, replication, WAL, and bloat indicators.
-<img
+<Image
src="/docs/img/guides/platform/supabase-grafana-prometheus.png"
alt="Supabase Grafana dashboard showcasing database metrics"
- className="mt-6 rounded-lg border border-foreground/10 shadow-xs"
+ width="3000"
+ height="1509"
/>
## 4. Configure alerts (optional)
diff --git a/apps/docs/content/guides/telemetry/metrics/grafana-self-hosted.mdx b/apps/docs/content/guides/telemetry/metrics/grafana-self-hosted.mdx
index 5e10dbd38a0..917ecfbc9e8 100644
--- a/apps/docs/content/guides/telemetry/metrics/grafana-self-hosted.mdx
+++ b/apps/docs/content/guides/telemetry/metrics/grafana-self-hosted.mdx
@@ -63,10 +63,11 @@ Install Grafana (Docker image, Helm chart, or packages) and connect it to Promet
You now have over 200 production-ready panels covering CPU, IO, WAL, replication, index bloat, and query throughput.
-<img
+<Image
src="/docs/img/guides/platform/supabase-grafana-prometheus.png"
alt="Supabase Grafana dashboard showcasing database metrics"
- className="mt-6 rounded-lg border border-foreground/10 shadow-xs"
+ width="3000"
+ height="1509"
/>
## 4. Configure alerting
diff --git a/apps/docs/content/guides/telemetry/metrics/vendor-agnostic.mdx b/apps/docs/content/guides/telemetry/metrics/vendor-agnostic.mdx
index 69d1291e8ec..12cb2746b9d 100644
--- a/apps/docs/content/guides/telemetry/metrics/vendor-agnostic.mdx
+++ b/apps/docs/content/guides/telemetry/metrics/vendor-agnostic.mdx
@@ -51,10 +51,11 @@ No matter which collector you use, you need to hit the Metrics API once per minu
- For other tools, group metrics by categories (CPU, IO, WAL, replication, connections) and recreate the visualizations that matter most to your team.
- Tag or relabel series with `project`, `env`, or `team` labels to make multi-project views easier.
-<img
+<Image
src="/docs/img/guides/platform/supabase-grafana-prometheus.png"
alt="Supabase Grafana dashboard showcasing database metrics"
- className="mt-6 rounded-lg border border-foreground/10 shadow-xs"
+ width="3000"
+ height="1509"
/>
## 4. Alerts and automation
diff --git a/apps/docs/internals/generate-guides-markdown.ts b/apps/docs/internals/generate-guides-markdown.ts
index be6a75bf2b6..5bdca3e1c73 100644
--- a/apps/docs/internals/generate-guides-markdown.ts
+++ b/apps/docs/internals/generate-guides-markdown.ts
@@ -13,12 +13,15 @@ import { parse as parseToml } from 'smol-toml'
import { mcpConfigPanelMarkdown as McpConfigPanel } from 'ui-patterns/McpUrlBuilder/McpConfigPanel.md'
import { addBaseUrlPrefix } from './internal-links'
+import { AccordionItem } from './markdown-schema/Accordion'
import { Admonition } from './markdown-schema/Admonition'
import { AuthProviders } from './markdown-schema/AuthProviders'
import { ComputeDiskLimitsTable } from './markdown-schema/ComputeDiskLimitsTable'
import { ContentListings } from './markdown-schema/ContentListings'
import { CustomContent } from './markdown-schema/CustomContent'
import { ErrorCodes } from './markdown-schema/ErrorCodes'
+import { IconCheck, IconX } from './markdown-schema/Icons'
+import { Image } from './markdown-schema/Image'
import { Link } from './markdown-schema/Link'
import { McpCiConfigBlock } from './markdown-schema/McpCiConfigBlock'
import { MetricsStackCards } from './markdown-schema/MetricsStackCards'
@@ -151,7 +154,11 @@ function applySchema(parent: Parent, schema: ComponentSchema): void {
* component not listed is unwrapped (children are kept, wrapper is dropped).
*/
const SCHEMA: ComponentSchema = {
+ AccordionItem,
Admonition,
+ IconCheck,
+ IconX,
+ Image,
AuthProviders,
ComputeDiskLimitsTable,
CustomContent,
diff --git a/apps/docs/internals/markdown-schema/Accordion.ts b/apps/docs/internals/markdown-schema/Accordion.ts
new file mode 100644
index 00000000000..6daa2be7f84
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/Accordion.ts
@@ -0,0 +1,10 @@
+export const AccordionItem = ({
+ props,
+ children,
+}: {
+ props: Record<string, unknown>
+ children: string
+}): string => {
+ const header = String(props.header ?? '').trim()
+ return header ? `**${header}**\n\n${children}` : children
+}
diff --git a/apps/docs/internals/markdown-schema/Icons.ts b/apps/docs/internals/markdown-schema/Icons.ts
new file mode 100644
index 00000000000..fe77b3f0a6e
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/Icons.ts
@@ -0,0 +1,2 @@
+export const IconCheck = (): string => '✅'
+export const IconX = (): string => '❌'
diff --git a/apps/docs/internals/markdown-schema/Image.ts b/apps/docs/internals/markdown-schema/Image.ts
new file mode 100644
index 00000000000..07c65b8281f
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/Image.ts
@@ -0,0 +1,21 @@
+import { getInternalLinkBaseUrl, withDocsBasePath } from '../internal-links'
+
+export const Image = ({ props }: { props: Record<string, unknown> }): string => {
+ const alt = String(props.alt ?? '')
+ const rawSrc = props.src as string
+
+ // propsFrom() always stores attribute values as strings: either the literal
+ // string value for `src="/..."`, or the raw JS expression for `src={{ dark, light }}`.
+ const srcStr = String(rawSrc ?? '')
+ let src = String(props.src)
+
+ if (!srcStr.startsWith('/')) {
+ // Object expression form: `src={{ dark: '/...', light: '/...' }}`
+ const match =
+ srcStr.match(/dark:\s*['"]([^'"]+)['"]/) ?? srcStr.match(/light:\s*['"]([^'"]+)['"]/)
+ src = match ? match[1] : ''
+ }
+
+ const baseUrl = getInternalLinkBaseUrl()
+ return `![${alt}](${baseUrl}${withDocsBasePath(src)})`
+}
diff --git a/apps/docs/internals/markdown-schema/Panel.ts b/apps/docs/internals/markdown-schema/Panel.ts
index 2962e24d403..30012844614 100644
--- a/apps/docs/internals/markdown-schema/Panel.ts
+++ b/apps/docs/internals/markdown-schema/Panel.ts
@@ -1,3 +1,14 @@
-export const Panel = ({ props }: { props: Record<string, unknown> }): string => {
- return String(props.title)
+export const Panel = ({
+ props,
+ children,
+}: {
+ props: Record<string, unknown>
+ children: string
+}): string => {
+ const title = String(props.title ?? '')
+ const description = children.replace(/\s+/g, ' ').trim()
+
+ if (title && description) return `${title}: ${description}`
+
+ return title || description
}