The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
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.tsxindex 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.tsxindex 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.utimport { 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.tsxindex 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsoncindex 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": {