Skip to content

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

fix: Add /docs to Link hrefs on markdown script (#46798)

Jeremias Menichelli9b438d3f8db7
diff --git a/apps/docs/internals/generate-guides-markdown.ts b/apps/docs/internals/generate-guides-markdown.ts
index a7be3589be5..6758ba073ac 100644
--- a/apps/docs/internals/generate-guides-markdown.ts
+++ b/apps/docs/internals/generate-guides-markdown.ts
@@ -3,7 +3,7 @@ import path from 'node:path'
import { globby } from 'globby'
import matter from 'gray-matter'
-import { getInternalLinkBaseUrl, prefixInternalLinks } from './internal-links'
+import { getInternalLinkBaseUrl, prefixInternalLinks, withDocsBasePath } from './internal-links'
const PARTIALS_DIR = path.join(process.cwd(), 'content', '_partials')
@@ -109,7 +109,7 @@ function convertLinkPanels(content: string): string {
return content.replace(/<Link\b([\s\S]*?)>([\s\S]*?)<\/Link>/g, (full, linkAttrs, body) => {
const hrefMatch = linkAttrs.match(/\bhref="([^"]+)"/)
if (!hrefMatch) return full
- const href = hrefMatch[1]
+ const href = withDocsBasePath(hrefMatch[1])
const panelOpen = body.match(/<(GlassPanel|IconPanel)\b/)
if (!panelOpen) return full
diff --git a/apps/docs/internals/internal-links.test.ts b/apps/docs/internals/internal-links.test.ts
index 4558e679f71..54a4bf783e5 100644
--- a/apps/docs/internals/internal-links.test.ts
+++ b/apps/docs/internals/internal-links.test.ts
@@ -1,6 +1,53 @@
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { getInternalLinkBaseUrl, prefixInternalLinks } from './internal-links'
+import { getInternalLinkBaseUrl, prefixInternalLinks, withDocsBasePath } from './internal-links'
+
+describe('withDocsBasePath', () => {
+ it('prepends /docs to a root-relative href', () => {
+ expect(withDocsBasePath('/guides/self-hosting/docker')).toBe('/docs/guides/self-hosting/docker')
+ })
+
+ it('prepends /docs to a single-segment href', () => {
+ expect(withDocsBasePath('/contribute')).toBe('/docs/contribute')
+ })
+
+ it('leaves hrefs that already start with /docs/ alone', () => {
+ expect(withDocsBasePath('/docs/guides/foo')).toBe('/docs/guides/foo')
+ })
+
+ it('leaves the exact /docs href alone', () => {
+ expect(withDocsBasePath('/docs')).toBe('/docs')
+ })
+
+ it('does not match prefixes like /docsx that only share leading chars', () => {
+ expect(withDocsBasePath('/docsx/foo')).toBe('/docs/docsx/foo')
+ })
+
+ it('leaves absolute http(s) URLs alone', () => {
+ expect(withDocsBasePath('https://example.com/foo')).toBe('https://example.com/foo')
+ })
+
+ it('leaves protocol-relative URLs alone', () => {
+ expect(withDocsBasePath('//cdn.example.com/foo')).toBe('//cdn.example.com/foo')
+ })
+
+ it('leaves anchor-only hrefs alone', () => {
+ expect(withDocsBasePath('#section')).toBe('#section')
+ })
+
+ it('leaves mailto: hrefs alone', () => {
+ expect(withDocsBasePath('mailto:[email protected]')).toBe('mailto:[email protected]')
+ })
+
+ it('leaves relative ./ and ../ hrefs alone', () => {
+ expect(withDocsBasePath('./sibling')).toBe('./sibling')
+ expect(withDocsBasePath('../parent')).toBe('../parent')
+ })
+
+ it('preserves query strings and fragments', () => {
+ expect(withDocsBasePath('/guides/foo?x=1#bar')).toBe('/docs/guides/foo?x=1#bar')
+ })
+})
describe('getInternalLinkBaseUrl', () => {
const ORIGINAL_ENV = process.env
diff --git a/apps/docs/internals/internal-links.ts b/apps/docs/internals/internal-links.ts
index 5742e007824..ae19af20595 100644
--- a/apps/docs/internals/internal-links.ts
+++ b/apps/docs/internals/internal-links.ts
@@ -1,3 +1,21 @@
+const DOCS_BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH || '/docs'
+
+/**
+ * Prepend the docs basePath to a root-relative href, mirroring what Next.js
+ * `<Link>` does at render time. Used when extracting an `href` attribute out
+ * of MDX `<Link>` components into plain markdown — without this, links like
+ * `/guides/foo` lose the `/docs` prefix the deployed site adds.
+ *
+ * Returns the href unchanged when it's already prefixed, external, anchor-
+ * only, or relative (`./`, `../`).
+ */
+export function withDocsBasePath(href: string): string {
+ if (!href.startsWith('/')) return href
+ if (href.startsWith('//')) return href
+ if (href === DOCS_BASE_PATH || href.startsWith(`${DOCS_BASE_PATH}/`)) return href
+ return `${DOCS_BASE_PATH}${href}`
+}
+
/**
* Returns the absolute base URL to prepend to root-relative markdown links
* (e.g. `/dashboard/...`). Empty when no rewrite should happen — typically