Skip to content

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

fix: Make markdown links absolute (#46773)

Jeremias Menichelli19ae3501e642
diff --git a/apps/docs/internals/generate-guides-markdown.ts b/apps/docs/internals/generate-guides-markdown.ts
index 8fdf3273617..a7be3589be5 100644
--- a/apps/docs/internals/generate-guides-markdown.ts
+++ b/apps/docs/internals/generate-guides-markdown.ts
@@ -3,6 +3,8 @@ import path from 'node:path'
import { globby } from 'globby'
import matter from 'gray-matter'
+import { getInternalLinkBaseUrl, prefixInternalLinks } from './internal-links'
+
const PARTIALS_DIR = path.join(process.cwd(), 'content', '_partials')
/**
@@ -195,6 +197,7 @@ function stripJsxTags(content: string): string {
async function generate() {
const files = await globby(['content/guides/**/!(_)*.mdx'])
+ const linkBaseUrl = getInternalLinkBaseUrl()
let warnings = 0
await Promise.all(
@@ -211,7 +214,8 @@ async function generate() {
const withPartials = await inlinePartials(rawContent)
const withSteps = convertStepHike(withPartials)
const withLinks = convertLinkPanels(withSteps)
- const processed = stripJsxTags(withLinks)
+ const stripped = stripJsxTags(withLinks)
+ const processed = prefixInternalLinks(stripped, linkBaseUrl)
const header = [
data.title ? `# ${data.title}` : '',
diff --git a/apps/docs/internals/generate-reference-markdown.ts b/apps/docs/internals/generate-reference-markdown.ts
index f216ff89e52..6c3b05997ff 100644
--- a/apps/docs/internals/generate-reference-markdown.ts
+++ b/apps/docs/internals/generate-reference-markdown.ts
@@ -3,6 +3,8 @@ import path from 'node:path'
import matter from 'gray-matter'
import yaml from 'js-yaml'
+import { getInternalLinkBaseUrl, prefixInternalLinks } from './internal-links'
+
const GENERATED = path.join(process.cwd(), 'features/docs/generated')
const OUT_DIR = path.join(process.cwd(), 'public/markdown/reference')
const MDX_ROOT = path.join(process.cwd(), 'docs/ref')
@@ -386,6 +388,7 @@ async function generate() {
const sharedTypeSpec = await readJson<TypeSpec>(
path.join(process.cwd(), 'content/reference/javascript/v2/typeSpec.json')
)
+ const linkBaseUrl = getInternalLinkBaseUrl()
await Promise.all(
REFERENCES.map(async (ref) => {
@@ -404,7 +407,7 @@ async function generate() {
output = await renderCli(ref)
break
}
- await fs.writeFile(path.join(OUT_DIR, ref.outFile), output)
+ await fs.writeFile(path.join(OUT_DIR, ref.outFile), prefixInternalLinks(output, linkBaseUrl))
})
)
diff --git a/apps/docs/internals/internal-links.test.ts b/apps/docs/internals/internal-links.test.ts
new file mode 100644
index 00000000000..4558e679f71
--- /dev/null
+++ b/apps/docs/internals/internal-links.test.ts
@@ -0,0 +1,194 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { getInternalLinkBaseUrl, prefixInternalLinks } from './internal-links'
+
+describe('getInternalLinkBaseUrl', () => {
+ const ORIGINAL_ENV = process.env
+
+ beforeEach(() => {
+ process.env = { ...ORIGINAL_ENV }
+ delete process.env.VERCEL_ENV
+ delete process.env.VERCEL_URL
+ })
+
+ afterEach(() => {
+ process.env = ORIGINAL_ENV
+ })
+
+ it('returns the production host when VERCEL_ENV=production', () => {
+ process.env.VERCEL_ENV = 'production'
+ expect(getInternalLinkBaseUrl()).toBe('https://supabase.com')
+ })
+
+ it('production wins even if VERCEL_URL is also set', () => {
+ process.env.VERCEL_ENV = 'production'
+ process.env.VERCEL_URL = 'should-be-ignored.vercel.app'
+ expect(getInternalLinkBaseUrl()).toBe('https://supabase.com')
+ })
+
+ it('returns the deployment URL when VERCEL_ENV=preview', () => {
+ process.env.VERCEL_ENV = 'preview'
+ process.env.VERCEL_URL = 'supabase-com-abc123.vercel.app'
+ expect(getInternalLinkBaseUrl()).toBe('https://supabase-com-abc123.vercel.app')
+ })
+
+ it('returns empty when preview is set but VERCEL_URL is missing', () => {
+ process.env.VERCEL_ENV = 'preview'
+ expect(getInternalLinkBaseUrl()).toBe('')
+ })
+
+ it('returns empty when VERCEL_ENV=development', () => {
+ process.env.VERCEL_ENV = 'development'
+ process.env.VERCEL_URL = 'localhost-tunnel.vercel.app'
+ expect(getInternalLinkBaseUrl()).toBe('')
+ })
+
+ it('returns empty when VERCEL_ENV is not set (local)', () => {
+ expect(getInternalLinkBaseUrl()).toBe('')
+ })
+})
+
+describe('prefixInternalLinks', () => {
+ const BASE = 'https://supabase.com'
+
+ it('returns content unchanged when baseUrl is empty', () => {
+ const input = 'See [Dashboard](/dashboard/foo).'
+ expect(prefixInternalLinks(input, '')).toBe(input)
+ })
+
+ it('prepends baseUrl to a root-relative link', () => {
+ expect(prefixInternalLinks('See [Dashboard](/dashboard/foo).', BASE)).toBe(
+ 'See [Dashboard](https://supabase.com/dashboard/foo).'
+ )
+ })
+
+ it('rewrites multiple links on the same line', () => {
+ const input = 'A [one](/a) and [two](/b/c) here.'
+ expect(prefixInternalLinks(input, BASE)).toBe(
+ 'A [one](https://supabase.com/a) and [two](https://supabase.com/b/c) here.'
+ )
+ })
+
+ it('preserves query strings and fragments', () => {
+ expect(prefixInternalLinks('[link](/foo?bar=1&baz=2#section)', BASE)).toBe(
+ '[link](https://supabase.com/foo?bar=1&baz=2#section)'
+ )
+ })
+
+ it('leaves absolute http(s) links alone', () => {
+ const input = 'See [GitHub](https://github.com/supabase).'
+ expect(prefixInternalLinks(input, BASE)).toBe(input)
+ })
+
+ it('leaves anchor-only links alone', () => {
+ const input = 'Jump to [section](#installation).'
+ expect(prefixInternalLinks(input, BASE)).toBe(input)
+ })
+
+ it('leaves mailto and other schemes alone', () => {
+ const input = 'Email [us](mailto:[email protected]) or [call](tel:+1234).'
+ expect(prefixInternalLinks(input, BASE)).toBe(input)
+ })
+
+ it('leaves explicitly relative links (./, ../) alone', () => {
+ const input = 'See [sibling](./sibling) and [parent](../parent).'
+ expect(prefixInternalLinks(input, BASE)).toBe(input)
+ })
+
+ it('leaves protocol-relative (//host) URLs alone', () => {
+ const input = 'CDN [asset](//cdn.example.com/img.png).'
+ expect(prefixInternalLinks(input, BASE)).toBe(input)
+ })
+
+ it('does not rewrite image syntax', () => {
+ const input = 'An image: ![alt text](/static/foo.png).'
+ expect(prefixInternalLinks(input, BASE)).toBe(input)
+ })
+
+ it('rewrites a link adjacent to an image without touching the image', () => {
+ expect(prefixInternalLinks('![logo](/logo.png) and [home](/dashboard)', BASE)).toBe(
+ '![logo](/logo.png) and [home](https://supabase.com/dashboard)'
+ )
+ })
+
+ it('skips links inside fenced code blocks', () => {
+ const input = [
+ 'Before: [yes](/touch-me).',
+ '',
+ '```md',
+ '[ignore me](/leave-alone)',
+ '```',
+ '',
+ 'After: [also yes](/touch-me-too).',
+ ].join('\n')
+
+ expect(prefixInternalLinks(input, BASE)).toBe(
+ [
+ 'Before: [yes](https://supabase.com/touch-me).',
+ '',
+ '```md',
+ '[ignore me](/leave-alone)',
+ '```',
+ '',
+ 'After: [also yes](https://supabase.com/touch-me-too).',
+ ].join('\n')
+ )
+ })
+
+ it('handles multiple fenced code blocks correctly', () => {
+ const input = [
+ '[a](/a)',
+ '```',
+ '[skip1](/skip1)',
+ '```',
+ '[b](/b)',
+ '```ts',
+ '[skip2](/skip2)',
+ '```',
+ '[c](/c)',
+ ].join('\n')
+
+ expect(prefixInternalLinks(input, BASE)).toBe(
+ [
+ '[a](https://supabase.com/a)',
+ '```',
+ '[skip1](/skip1)',
+ '```',
+ '[b](https://supabase.com/b)',
+ '```ts',
+ '[skip2](/skip2)',
+ '```',
+ '[c](https://supabase.com/c)',
+ ].join('\n')
+ )
+ })
+
+ it('rewrites links with empty text', () => {
+ expect(prefixInternalLinks('[](/foo)', BASE)).toBe('[](https://supabase.com/foo)')
+ })
+
+ it('uses any baseUrl passed in, not just supabase.com', () => {
+ expect(prefixInternalLinks('[x](/y)', 'https://branch-deploy.vercel.app')).toBe(
+ '[x](https://branch-deploy.vercel.app/y)'
+ )
+ })
+
+ it('is a no-op when there are no matching links', () => {
+ const input = '# Title\n\nJust prose, no links.'
+ expect(prefixInternalLinks(input, BASE)).toBe(input)
+ })
+
+ it('handles an unclosed code fence by leaving the unclosed portion untouched', () => {
+ // A `split(/(```...```)/)` only pairs complete fences; an unclosed fence
+ // means everything after it stays in the trailing prose segment. Document
+ // that behavior rather than promising to parse malformed markdown.
+ const input = ['[before](/before)', '```', '[inside-unclosed](/inside)'].join('\n')
+ expect(prefixInternalLinks(input, BASE)).toBe(
+ [
+ '[before](https://supabase.com/before)',
+ '```',
+ '[inside-unclosed](https://supabase.com/inside)',
+ ].join('\n')
+ )
+ })
+})
diff --git a/apps/docs/internals/internal-links.ts b/apps/docs/internals/internal-links.ts
new file mode 100644
index 00000000000..5742e007824
--- /dev/null
+++ b/apps/docs/internals/internal-links.ts
@@ -0,0 +1,39 @@
+/**
+ * Returns the absolute base URL to prepend to root-relative markdown links
+ * (e.g. `/dashboard/...`). Empty when no rewrite should happen — typically
+ * local development, where keeping links relative lets them resolve against
+ * whatever host the dev server is on.
+ *
+ * Resolution order:
+ * - `VERCEL_ENV=production` → `https://supabase.com`
+ * - `VERCEL_ENV=preview` → `https://${VERCEL_URL}`
+ * - anything else → ''
+ */
+export function getInternalLinkBaseUrl(): string {
+ const env = process.env.VERCEL_ENV
+ if (env === 'production') return 'https://supabase.com'
+ if (env === 'preview' && process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`
+ return ''
+}
+
+/**
+ * Rewrite root-relative markdown links by prepending `baseUrl`:
+ * `[text](/foo)` → `[text](${baseUrl}/foo)`
+ *
+ * Skips fenced code blocks, image syntax (`![alt](...)`), protocol-relative
+ * URLs (`//host/...`), and non-root-relative targets (`http://`, `mailto:`,
+ * `#anchor`, `./`, `../`).
+ */
+export function prefixInternalLinks(content: string, baseUrl: string): string {
+ if (!baseUrl) return content
+ const segments = content.split(/(```[\s\S]*?```)/g)
+ return segments
+ .map((seg, i) => {
+ if (i % 2 === 1) return seg
+ return seg.replace(/(?<!!)(\[[^\]]*\])\((\/[^)\s]*)\)/g, (match, text, url) => {
+ if (url.startsWith('//')) return match
+ return `${text}(${baseUrl}${url})`
+ })
+ })
+ .join('')
+}