Skip to content

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

feat(docs): manifest-gated markdown alternate helper (#48389)

Pamela Chia65e786ba1311
diff --git a/apps/docs/app/guides/troubleshooting/[slug]/page.tsx b/apps/docs/app/guides/troubleshooting/[slug]/page.tsx
index 9f15cac7d53..40d22deedb3 100644
--- a/apps/docs/app/guides/troubleshooting/[slug]/page.tsx
+++ b/apps/docs/app/guides/troubleshooting/[slug]/page.tsx
@@ -1,9 +1,9 @@
-import { notFound } from 'next/navigation'
-
import TroubleshootingPage from '~/features/docs/Troubleshooting.page'
import { getAllTroubleshootingEntries, getArticleSlug } from '~/features/docs/Troubleshooting.utils'
import { PROD_URL } from '~/lib/constants'
import { getCustomContent } from '~/lib/custom-content/getCustomContent'
+import { mdAlternate } from '~/lib/md-alternates'
+import { notFound } from 'next/navigation'
export const dynamicParams = false
@@ -38,6 +38,7 @@ export const generateMetadata = async (props: { params: Promise<{ slug: string }
title: `${metadataTitle || 'Supabase'} | Troubleshooting${entry ? ` | ${entry.data.title}` : ''}`,
alternates: {
canonical: `${PROD_URL}/guides/troubleshooting/${slug}`,
+ types: mdAlternate(`troubleshooting/${slug}`),
},
}
}
diff --git a/apps/docs/app/guides/troubleshooting/page.tsx b/apps/docs/app/guides/troubleshooting/page.tsx
index 19e92851bb5..66d34249eb9 100644
--- a/apps/docs/app/guides/troubleshooting/page.tsx
+++ b/apps/docs/app/guides/troubleshooting/page.tsx
@@ -14,6 +14,7 @@ import { TROUBLESHOOTING_CONTAINER_ID } from '~/features/docs/Troubleshooting.ut
import { SidebarSkeleton } from '~/layouts/MainSkeleton'
import { PROD_URL } from '~/lib/constants'
import { getCustomContent } from '~/lib/custom-content/getCustomContent'
+import { mdAlternate } from '~/lib/md-alternates'
import { type Metadata } from 'next'
const { metadataTitle } = getCustomContent(['metadata:title'])
@@ -62,5 +63,6 @@ export const metadata: Metadata = {
title: `${metadataTitle || 'Supabase'} | Troubleshooting`,
alternates: {
canonical: `${PROD_URL}/guides/troubleshooting`,
+ types: mdAlternate('troubleshooting'),
},
}
diff --git a/apps/docs/app/page.tsx b/apps/docs/app/page.tsx
index 452dad13110..27e6a28281c 100644
--- a/apps/docs/app/page.tsx
+++ b/apps/docs/app/page.tsx
@@ -28,10 +28,7 @@ const generateMetadata = async (_, parent: ResolvingMetadata): Promise<Metadata>
...(parentAlternates && {
languages: parentAlternates.languages || undefined,
media: parentAlternates.media || undefined,
- types: {
- ...(parentAlternates.types ?? {}),
- 'text/markdown': 'https://supabase.com/llms-full.txt',
- },
+ types: parentAlternates.types || undefined,
}),
},
}
diff --git a/apps/docs/features/docs/GuidesMdx.utils.tsx b/apps/docs/features/docs/GuidesMdx.utils.tsx
index 70a23ed0961..ab1d34c6494 100644
--- a/apps/docs/features/docs/GuidesMdx.utils.tsx
+++ b/apps/docs/features/docs/GuidesMdx.utils.tsx
@@ -9,6 +9,7 @@ import { generateOpenGraphImageMeta } from '~/features/seo/openGraph'
import { BASE_PATH } from '~/lib/constants'
import { getCustomContent } from '~/lib/custom-content/getCustomContent'
import { GUIDES_DIRECTORY, isValidGuideFrontmatter, type GuideFrontmatter } from '~/lib/docs'
+import { mdAlternate } from '~/lib/md-alternates'
import { GuideModelLoader } from '~/resources/guide/guideModelLoader'
import { fromMarkdown } from 'mdast-util-from-markdown'
import { gfmFromMarkdown } from 'mdast-util-gfm'
@@ -182,7 +183,7 @@ const genGuideMeta =
canonical: meta.canonical || `${BASE_PATH}${pathname}`,
types: {
...(parentAlternates?.types ?? {}),
- 'text/markdown': `${BASE_PATH}${pathname}.md`,
+ ...mdAlternate(pathname.replace(/^\/guides\//, '')),
},
},
openGraph: {
diff --git a/apps/docs/features/docs/TroubleshootingSection.page.tsx b/apps/docs/features/docs/TroubleshootingSection.page.tsx
index 9fdeb8b6173..3cb49e2ca37 100644
--- a/apps/docs/features/docs/TroubleshootingSection.page.tsx
+++ b/apps/docs/features/docs/TroubleshootingSection.page.tsx
@@ -1,18 +1,18 @@
-import { type Metadata } from 'next'
-
-import { TroubleshootingHeader, TroubleshootingEntries } from '~/features/docs/Troubleshooting.ui'
+import { TroubleshootingEntries, TroubleshootingHeader } from '~/features/docs/Troubleshooting.ui'
import {
TroubleshootingFilterEmptyState,
TroubleshootingListController,
} from '~/features/docs/Troubleshooting.ui.client'
import {
- type ITroubleshootingMetadata,
getTroubleshootingEntriesByTopic,
getTroubleshootingErrorsByTopic,
getTroubleshootingKeywordsByTopic,
+ type ITroubleshootingMetadata,
} from '~/features/docs/Troubleshooting.utils'
import { PROD_URL } from '~/lib/constants'
import { getCustomContent } from '~/lib/custom-content/getCustomContent'
+import { mdAlternate } from '~/lib/md-alternates'
+import { type Metadata } from 'next'
const { metadataTitle } = getCustomContent(['metadata:title'])
@@ -66,6 +66,7 @@ export function generateSectionTroubleshootingMetadata(
title: `${metadataTitle ?? 'Supabase'} | ${sectionName} Troubleshooting`,
alternates: {
canonical: `${PROD_URL}/guides/${topic}/troubleshooting`,
+ types: mdAlternate(`${topic}/troubleshooting`),
},
}
}
diff --git a/apps/docs/lib/md-alternates.test.ts b/apps/docs/lib/md-alternates.test.ts
new file mode 100644
index 00000000000..9aa9296f111
--- /dev/null
+++ b/apps/docs/lib/md-alternates.test.ts
@@ -0,0 +1,117 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { PROD_URL } from '~/lib/constants'
+import { describe, expect, it, vi } from 'vitest'
+
+import { mdAlternate } from './md-alternates'
+
+vi.mock('~/public/markdown/manifest.json', () => ({
+ default: [
+ 'getting-started/quickstarts/react',
+ 'troubleshooting/all-about-supabase-egress-a_Sg_e',
+ 'troubleshooting',
+ ],
+}))
+
+describe('mdAlternate', () => {
+ it('returns the absolute .md sibling for a manifest-listed guide slug', () => {
+ expect(mdAlternate('getting-started/quickstarts/react')).toEqual({
+ 'text/markdown': `${PROD_URL}/guides/getting-started/quickstarts/react.md`,
+ })
+ })
+
+ it('returns the sibling for a troubleshooting entry', () => {
+ expect(mdAlternate('troubleshooting/all-about-supabase-egress-a_Sg_e')).toEqual({
+ 'text/markdown': `${PROD_URL}/guides/troubleshooting/all-about-supabase-egress-a_Sg_e.md`,
+ })
+ })
+
+ it('returns the sibling for the troubleshooting index', () => {
+ expect(mdAlternate('troubleshooting')).toEqual({
+ 'text/markdown': `${PROD_URL}/guides/troubleshooting.md`,
+ })
+ })
+
+ it('returns undefined for slugs without generated markdown', () => {
+ expect(mdAlternate('database/extensions/wrappers/s3')).toBeUndefined()
+ expect(mdAlternate('local-development/cli/config')).toBeUndefined()
+ })
+})
+
+const WIRING: [string, string][] = [
+ ['features/docs/GuidesMdx.utils.tsx', 'mdAlternate('],
+ ['app/guides/troubleshooting/[slug]/page.tsx', 'mdAlternate(`troubleshooting/${slug}`)'],
+ ['app/guides/troubleshooting/page.tsx', "mdAlternate('troubleshooting')"],
+ ['features/docs/TroubleshootingSection.page.tsx', 'mdAlternate(`${topic}/troubleshooting`)'],
+]
+
+describe('markdown alternate wiring', () => {
+ it('every tag emitter routes through mdAlternate', async () => {
+ for (const [file, wiring] of WIRING) {
+ const source = await fs.readFile(path.join(process.cwd(), file), 'utf-8')
+ expect(source.includes(wiring), `${file} must contain "${wiring}"`).toBe(true)
+ }
+ })
+
+ it('the generator registers the troubleshooting index in the manifest', async () => {
+ const source = await fs.readFile(
+ path.join(process.cwd(), 'internals/generate-guides-markdown.ts'),
+ 'utf-8'
+ )
+ expect(source.includes("renderManifest(sources, ['troubleshooting'])")).toBe(true)
+ })
+})
+
+const SCAN_ROOTS = ['app', 'components', 'features', 'lib', 'internals']
+const ALLOWED_MD_LITERAL_FILES = new Set([
+ 'lib/md-alternates.ts',
+ 'app/api/guides-md/[...slug]/route.ts',
+])
+
+function isScannableSource(fileName: string): boolean {
+ return (
+ /\.(ts|tsx)$/.test(fileName) &&
+ !/\.test\.(ts|tsx)$/.test(fileName) &&
+ !fileName.endsWith('.d.ts')
+ )
+}
+
+async function collectSourceFiles(dir: string): Promise<string[]> {
+ const dirents = await fs.readdir(dir, { withFileTypes: true })
+ const files: string[] = []
+ for (const dirent of dirents) {
+ const full = path.join(dir, dirent.name)
+ if (dirent.isDirectory()) {
+ if (dirent.name === 'node_modules') continue
+ files.push(...(await collectSourceFiles(full)))
+ } else if (isScannableSource(dirent.name)) {
+ files.push(full)
+ }
+ }
+ return files
+}
+
+describe('no hardcoded text/markdown outside the helper', () => {
+ it('every text/markdown occurrence lives in an allowed file', async () => {
+ const rootFiles = (await fs.readdir(process.cwd(), { withFileTypes: true }))
+ .filter((dirent) => dirent.isFile() && isScannableSource(dirent.name))
+ .map((dirent) => path.join(process.cwd(), dirent.name))
+ const nestedFiles = (
+ await Promise.all(
+ SCAN_ROOTS.map((root) => collectSourceFiles(path.join(process.cwd(), root)))
+ )
+ ).flat()
+
+ const offenders = (
+ await Promise.all(
+ [...rootFiles, ...nestedFiles].map(async (file) => {
+ const rel = path.relative(process.cwd(), file)
+ if (ALLOWED_MD_LITERAL_FILES.has(rel)) return null
+ const source = await fs.readFile(file, 'utf-8')
+ return source.includes('text/markdown') ? rel : null
+ })
+ )
+ ).filter((rel): rel is string => rel !== null)
+ expect(offenders, `hardcoded text/markdown in: ${offenders.join(', ')}`).toEqual([])
+ })
+})
diff --git a/apps/docs/lib/md-alternates.ts b/apps/docs/lib/md-alternates.ts
new file mode 100644
index 00000000000..6e2294acbc0
--- /dev/null
+++ b/apps/docs/lib/md-alternates.ts
@@ -0,0 +1,9 @@
+import { PROD_URL } from '~/lib/constants'
+import MARKDOWN_SLUGS from '~/public/markdown/manifest.json'
+
+const SLUGS = new Set<string>(MARKDOWN_SLUGS)
+
+export function mdAlternate(slug: string): { 'text/markdown': string } | undefined {
+ if (!SLUGS.has(slug)) return undefined
+ return { 'text/markdown': `${PROD_URL}/guides/${slug}.md` }
+}
diff --git a/apps/docs/turbo.jsonc b/apps/docs/turbo.jsonc
index 9d663a7ff71..3bd522d3235 100644
--- a/apps/docs/turbo.jsonc
+++ b/apps/docs/turbo.jsonc
@@ -10,10 +10,21 @@
"inputs": ["spec/**"],
"outputs": ["features/docs/generated/**"],
},
+ // Fetches remote (GitHub) content and the JSON artifacts the markdown generator reads.
+ // Not cached: the inputs are remote, so a cache restore could resurrect stale content.
+ "build:federated-content": {
+ "cache": false,
+ "env": [
+ "DOCS_GITHUB_APP_ID",
+ "DOCS_GITHUB_APP_INSTALLATION_ID",
+ "DOCS_GITHUB_APP_PRIVATE_KEY",
+ ],
+ },
// Generates the guide/reference .md files and manifest.json under public/markdown/.
// Declaring outputs lets Turbo restore these artifacts on a cache hit; without it a
// cached run would skip the script and leave the generated markdown missing for `next build`.
"build:markdown": {
+ "dependsOn": ["build:federated-content"],
"outputs": ["public/markdown/**", "public/markdown/manifest.json"],
},
"test": {