The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feat: Generate sitemap.md file in kb, fix markdown slug reconciliation, update llms file (#52076)
Jeremias Menichelli497cbecfd3b3
diff --git a/apps/kb/.gitignore b/apps/kb/.gitignoreindex 57a0cf1c109..c09eca3d740 100644--- a/apps/kb/.gitignore+++ b/apps/kb/.gitignore@@ -1,7 +1,7 @@# build outputdist/-# generated markdown export (scripts/generate-markdown.mjs)+# generated markdown export (scripts/generate-markdown.ts)public/markdown/# federated troubleshooting content (scripts/federated-content), regenerated on every prebuilddiff --git a/apps/kb/AGENTS.md b/apps/kb/AGENTS.mdindex 8f2ab71c5f4..c967da16390 100644--- a/apps/kb/AGENTS.md+++ b/apps/kb/AGENTS.md@@ -54,8 +54,8 @@ Each content collection renders through a matching catch-all page — e.g. `src/(`src/pages/topics/[topic].astro`) are generated from the `TOPICS` list in `src/lib/topics.ts`, not fromcontent files, and read from every collection.-Separately, `scripts/generate-markdown.mjs` runs as a `prebuild` step and exports every content file — plus-one page per topic, listing its guides — as a plain `.md` file under the gitignored `public/markdown/`,+Separately, `scripts/generate-markdown.ts` runs as a `prebuild` step and exports every content file — plus+one page per topic, listing its guides, and a root `sitemap.md` linking every topic, troubleshooting article, and guide — as a plain `.md` file under the gitignored `public/markdown/`,mirroring the page's URL with a `.md` extension. `vercel.json` permanently redirects `<page>.md` requests tothese generated files, one redirect entry per route section (`guides`, `topics`, `troubleshooting`). It alsorewrites guide, topic, and troubleshooting page requests that send `Accept: text/markdown` to the same files@@ -65,7 +65,7 @@ rewrites guide, topic, and troubleshooting page requests that send `Accept: textIf you add a new content collection or top-level route, add a matching redirect, negotiated rewrite, and`Vary: Accept` header in `vercel.json` (`/kb/<section>/:path+.md` → `/kb/markdown/<section>/:path+.md`, the`Accept` rewrite to `/markdown/<section>/:path+.md`, and a `headers` entry for `/kb/<section>/:path+`), and-check whether `generate-markdown.mjs` needs updating too — the content export falls out of its generic+check whether `generate-markdown.ts` needs updating too — the content export falls out of its generic`src/content/**` walk automatically, but per-topic-style listing pages don't.## Topic-specific guidancediff --git a/apps/kb/package.json b/apps/kb/package.jsonindex 9e0135c48bd..c28ef445732 100644--- a/apps/kb/package.json+++ b/apps/kb/package.json@@ -10,7 +10,7 @@"prebuild": "pnpm run fetch:federated-content && pnpm run generate:markdown","build": "astro build","fetch:federated-content": "tsx ./scripts/federated-content/fetch-federated-content.ts",- "generate:markdown": "tsx ./scripts/generate-markdown.mjs",+ "generate:markdown": "tsx ./scripts/generate-markdown.ts","presearch:ingest": "pnpm run fetch:federated-content && pnpm run generate:markdown","search:ingest": "tsx ./scripts/search/ingest.ts","sync:legacy-slugs": "tsx ./scripts/federated-content/backfill-legacy-slugs.ts",diff --git a/apps/kb/scripts/generate-markdown.test.mjs b/apps/kb/scripts/generate-markdown.test.tssimilarity index 84%rename from apps/kb/scripts/generate-markdown.test.mjsrename to apps/kb/scripts/generate-markdown.test.tsindex 7f4c08b2edc..35633c9086f 100644--- a/apps/kb/scripts/generate-markdown.test.mjs+++ b/apps/kb/scripts/generate-markdown.test.ts@@ -5,8 +5,9 @@ import {getInternalLinkBaseUrl,parseFrontmatter,renderMarkdown,+ renderSitemapMarkdown,renderTopicMarkdown,-} from './generate-markdown.mjs'+} from './generate-markdown.ts'describe('parseFrontmatter', () => {it('parses title/description out of the YAML frontmatter and returns the rest as body', () => {@@ -175,3 +176,28 @@ describe('renderTopicMarkdown', () => {)})})++describe('renderSitemapMarkdown', () => {+ it('renders the site title and description, then a linked list for topics, troubleshooting and guides', () => {+ const markdown = renderSitemapMarkdown({+ topics: [{ title: 'Auth', url: 'https://supabase.com/kb/topics/auth.md' }],+ troubleshooting: [+ { title: 'Permission denied', url: 'https://supabase.com/kb/troubleshooting/denied.md' },+ ],+ guides: [{ title: 'Sample guide', url: 'https://supabase.com/kb/guides/sample-guide.md' }],+ })++ expect(markdown).toBe(+ [+ '# Supabase Knowledge Base',+ 'In-depth guides, tutorials, troubleshooting, and explainers for best practices for Supabase',+ '## Topics',+ '- [Auth](https://supabase.com/kb/topics/auth.md)',+ '## Troubleshooting',+ '- [Permission denied](https://supabase.com/kb/troubleshooting/denied.md)',+ '## Guides',+ '- [Sample guide](https://supabase.com/kb/guides/sample-guide.md)',+ ].join('\n\n') + '\n'+ )+ })+})diff --git a/apps/kb/scripts/generate-markdown.mjs b/apps/kb/scripts/generate-markdown.tssimilarity index 69%rename from apps/kb/scripts/generate-markdown.mjsrename to apps/kb/scripts/generate-markdown.tsindex fb133e2c4c9..b3e83f49935 100644--- a/apps/kb/scripts/generate-markdown.mjs+++ b/apps/kb/scripts/generate-markdown.ts@@ -1,4 +1,3 @@-#!/usr/bin/env node// Pre-build step: exports every src/content/**/*.{md,mdx} file as a plain// .md file under public/markdown/, for agents/tools that want the raw// content instead of the rendered page (same idea as apps/docs' guides@@ -15,7 +14,7 @@ import { visit } from 'unist-util-visit'import YAML from 'yaml'import { BASE_PATH } from '../src/lib/constants.ts'-import { isInTopic, TOPICS, topicToSlug } from '../src/lib/topics.ts'+import { isInTopic, TOPICS, topicToSlug, type Topic } from '../src/lib/topics.ts'const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url))const CONTENT_DIR = path.join(SCRIPT_DIR, '..', 'src', 'content')@@ -25,6 +24,22 @@ const OUTPUT_DIR = path.join(SCRIPT_DIR, '..', 'public', 'markdown')// makes sense read on its own.const SITE_ORIGIN = 'https://supabase.com'+const SITE_TITLE = 'Supabase Knowledge Base'+const SITE_DESCRIPTION =+ 'In-depth guides, tutorials, troubleshooting, and explainers for best practices for Supabase'++interface Frontmatter {+ title?: string+ description?: string+ topics?: unknown+ [key: string]: unknown+}++interface Entry {+ title: string+ url: string+}+// Single processor reused for every file: parses GFM markdown to an mdast// tree and serializes it back, same extensions on both ends so nothing// (tables, strikethrough, alert blockquotes) gets mangled in the round trip.@@ -59,9 +74,8 @@ export function getInternalLinkBaseUrl() {* with plain string ops, and the frontmatter itself is parsed with a real* YAML parser — no regex involved in extracting values.*- * @param {string} raw*/-export function parseFrontmatter(raw) {+export function parseFrontmatter(raw: string): { data: Frontmatter; body: string } {if (!raw.startsWith('---\n')) return { data: {}, body: raw }const frontmatterEnd = raw.indexOf('\n---', 4)@@ -80,9 +94,8 @@ export function parseFrontmatter(raw) {* back — the AST equivalent of apps/docs' `addBaseUrlPrefix()`, so this file* still makes sense read outside of the site (no regex over the raw text).*- * @param {string} body*/-export function absolutizeLinks(body) {+export function absolutizeLinks(body: string): string {const tree = processor.parse(body)const baseUrl = getInternalLinkBaseUrl()@@ -102,11 +115,8 @@ export function absolutizeLinks(body) {* Renders the simplified export: the frontmatter title as an h1, the* description as the paragraph beneath it, then the (link-absolutized)* body.- *- * @param {{ title?: string; description?: string }} data- * @param {string} body*/-export function renderMarkdown(data, body) {+export function renderMarkdown(data: Frontmatter, body: string): string {const heading = data.title ? `# ${data.title}\n\n` : ''const lead = data.description ? `${data.description}\n\n` : ''// absolutizeLinks() already normalizes to exactly one trailing newline@@ -119,32 +129,67 @@ export function renderMarkdown(data, body) {* paragraph beneath it, then a bullet list linking to every guide tagged* with that topic — same data `src/pages/topics/[topic].astro` renders,* as a plain markdown page.- *- * @param {{ name: string; description: string }} topic- * @param {{ title: string; url: string }[]} guides*/-export function renderTopicMarkdown(topic, guides) {+export function renderTopicMarkdown(+ topic: { name: string; description: string },+ guides: Entry[]+): string {const list = guides.length? guides.map((guide) => `- [${guide.title}](${guide.url})`).join('\n'): 'No guides for this topic'return `# ${topic.name}\n\n${topic.description}\n\n${list}\n`}+const renderLinkList = (entries: Entry[]) =>+ entries.length+ ? entries.map((entry) => `- [${entry.title}](${entry.url})`).join('\n')+ : 'No entries'++/**+ * Renders the root sitemap: the site title as an h1 with its description+ * beneath, then one section per kind of page (topics, troubleshooting+ * articles, guides), each a bullet list of links to the `.md` exports.+ */+export function renderSitemapMarkdown({+ topics,+ troubleshooting,+ guides,+}: {+ topics: Entry[]+ troubleshooting: Entry[]+ guides: Entry[]+}): string {+ return (+ [+ `# ${SITE_TITLE}`,+ SITE_DESCRIPTION,+ '## Topics',+ renderLinkList(topics),+ '## Troubleshooting',+ renderLinkList(troubleshooting),+ '## Guides',+ renderLinkList(guides),+ ].join('\n\n') + '\n'+ )+}+// file.mdx -> file.md, file.md -> file.md — no regex, just a suffix swap.-function toMdExtension(fileName) {+function toMdExtension(fileName: string): string {if (fileName.endsWith('.mdx')) return `${fileName.slice(0, -'.mdx'.length)}.md`return fileName}// Strips the .md/.mdx extension off a content-relative path and turns it// into the full, absolute URL of that page's markdown export.-function toGuideUrl(relativePath) {+function toMdUrl(relativePath: string): string {const posixPath = relativePath.split(path.sep).join('/')const withoutExt = toMdExtension(posixPath).slice(0, -'.md'.length)return `${SITE_ORIGIN}${BASE_PATH}/${withoutExt}.md`}-async function findContentFiles(dir) {+const byTitle = (a: Entry, b: Entry) => a.title.localeCompare(b.title)++async function findContentFiles(dir: string): Promise<string[]> {const entries = await readdir(dir, { withFileTypes: true })const files = await Promise.all(entries.map((entry) => {@@ -157,7 +202,7 @@ async function findContentFiles(dir) {return files.flat()}-async function writeFileEnsuringDir(outputPath, contents) {+async function writeFileEnsuringDir(outputPath: string, contents: string) {await mkdir(path.dirname(outputPath), { recursive: true })await writeFile(outputPath, contents)}@@ -165,7 +210,8 @@ async function writeFileEnsuringDir(outputPath, contents) {async function main() {const files = await findContentFiles(CONTENT_DIR)- const guidesByTopic = new Map(TOPICS.map((topic) => [topic.name, []]))+ const guidesByTopic = new Map<Topic, Entry[]>(TOPICS.map((topic) => [topic.name, []]))+ const entriesByCollection: Record<string, Entry[]> = { guides: [], troubleshooting: [] }await Promise.all(files.map(async (file) => {@@ -178,22 +224,36 @@ async function main() {await writeFileEnsuringDir(outputPath, markdown)// the first folder under src/content is the collection, e.g. guides or troubleshooting- const collection = relativePath.split(path.sep)[0]- const topics = Array.isArray(data.topics) ? data.topics : []- const guide = { title: data.title, url: toGuideUrl(relativePath) }+ const collection = relativePath.split(path.sep)[0] as 'guides' | 'troubleshooting'+ const topics: string[] = Array.isArray(data.topics) ? data.topics : []+ const entry: Entry = { title: data.title ?? relativePath, url: toMdUrl(relativePath) }+ entriesByCollection[collection]?.push(entry)for (const { name } of TOPICS) {- if (isInTopic({ collection, topics, topic: name })) guidesByTopic.get(name).push(guide)+ if (isInTopic({ collection, topics, topic: name })) guidesByTopic.get(name)!.push(entry)}}))- await Promise.all(- TOPICS.map((topic) => {- const markdown = renderTopicMarkdown(topic, guidesByTopic.get(topic.name))+ const topicEntries: Entry[] = TOPICS.map((topic) => ({+ title: topic.name,+ url: toMdUrl(`topics/${topicToSlug(topic.name)}.md`),+ }))++ await Promise.all([+ ...TOPICS.map((topic) => {+ const markdown = renderTopicMarkdown(topic, guidesByTopic.get(topic.name)!)const outputPath = path.join(OUTPUT_DIR, 'topics', `${topicToSlug(topic.name)}.md`)return writeFileEnsuringDir(outputPath, markdown)- })- )+ }),+ writeFileEnsuringDir(+ path.join(OUTPUT_DIR, 'sitemap.md'),+ renderSitemapMarkdown({+ topics: topicEntries,+ troubleshooting: entriesByCollection.troubleshooting.sort(byTitle),+ guides: entriesByCollection.guides.sort(byTitle),+ })+ ),+ ])}if (process.argv[1] === fileURLToPath(import.meta.url)) {diff --git a/apps/kb/src/content.config.ts b/apps/kb/src/content.config.tsindex 7d154553738..77200347ce1 100644--- a/apps/kb/src/content.config.ts+++ b/apps/kb/src/content.config.ts@@ -15,6 +15,12 @@ const formatDate = (date: Date): string => {}).format(adjusted)}+// Astro's default id is a lowercased slug of the file path, but the markdown+// export (scripts/generate-markdown.ts) keeps the filename's case and Vercel+// serves static files case-sensitively. Keeping the case here makes the page+// URL and the `.md` export path line up.+const generateId = ({ entry }: { entry: string }) => entry.replace(/\.mdx?$/, '')+// Every entry here is rendered through GuideLayout by// Shared by every article-like collection (guides, troubleshooting) so their// schemas can't drift on these fields — both render through ArticleLayout via@@ -31,7 +37,7 @@ const articleFields = {// src/pages/guides/[...slug].astro — dropping a new file in// src/content/guides doesn't need any per-file layout wiring.const guides = defineCollection({- loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/guides' }),+ loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/guides', generateId }),schema: z.object({...articleFields,description: z.string(),@@ -53,7 +59,7 @@ const guides = defineCollection({// entirely generated, never hand-authored, see .gitignore. Rendered through// ArticleLayout by src/pages/troubleshooting/[...slug].astro.const troubleshooting = defineCollection({- loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/troubleshooting' }),+ loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/troubleshooting', generateId }),schema: z.object({...articleFields,// The source has no description field, and ArticleLayout alreadydiff --git a/apps/kb/src/lib/topics.ts b/apps/kb/src/lib/topics.tsindex 1c8d024f794..acfadb24c14 100644--- a/apps/kb/src/lib/topics.ts+++ b/apps/kb/src/lib/topics.ts@@ -116,7 +116,7 @@ export const FORMAT_TOPICS: Topic[] = [export const pickCoverTopic = (topics: Topic[]): Topic | null =>topics.find((topic) => FORMAT_TOPICS.includes(topic)) ?? topics[0] ?? null-// the topic pages and scripts/generate-markdown.mjs both use this, so they list the same entries+// the topic pages and scripts/generate-markdown.ts both use this, so they list the same entriesexport const isInTopic = ({ collection, topics, topic }: IsInTopicParams): boolean => {if (collection !== 'troubleshooting') return topics.includes(topic)// troubleshooting is a content type. other type topics never list itdiff --git a/apps/kb/vercel.json b/apps/kb/vercel.jsonindex ce9ef14fb96..8af8b810171 100644--- a/apps/kb/vercel.json+++ b/apps/kb/vercel.json@@ -3,6 +3,7 @@"trailingSlash": false,"redirects": [{ "source": "/", "destination": "/kb", "permanent": false },+ { "source": "/kb/sitemap.md", "destination": "/kb/markdown/sitemap.md", "permanent": true },{"source": "/kb/guides/:path+.md","destination": "/kb/markdown/guides/:path+.md",diff --git a/apps/www/app/llms.txt/route.ts b/apps/www/app/llms.txt/route.tsindex d816e8e6724..d35285cf7f8 100644--- a/apps/www/app/llms.txt/route.ts+++ b/apps/www/app/llms.txt/route.ts@@ -96,6 +96,8 @@ export async function GET() {'',sourceLinks,'',+ '- [Knowledge Base](https://supabase.com/kb/sitemap.md)',+ '','## Pricing','','- [Supabase Pricing](https://supabase.com/pricing.md)',diff --git a/apps/www/lib/redirects.js b/apps/www/lib/redirects.jsindex f886d7a10f0..626ac54712d 100644--- a/apps/www/lib/redirects.js+++ b/apps/www/lib/redirects.js@@ -3428,6 +3428,7 @@ module.exports = [{ permanent: true, source: '/vector.md', destination: '/modules/vector.md' },{ permanent: true, source: '/homepage.md', destination: '/index.md' },{ permanent: true, source: '/.md', destination: '/index.md' },+ { permanent: true, source: '/kb.md', destination: '/kb/sitemap.md' },{ permanent: true, source: '/index', destination: '/' },// High-traffic 404s{ permanent: true, source: '/docs/graphql', destination: '/docs/guides/graphql' },