Skip to content

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

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/.gitignore
index 57a0cf1c109..c09eca3d740 100644
--- a/apps/kb/.gitignore
+++ b/apps/kb/.gitignore
@@ -1,7 +1,7 @@
# build output
dist/
-# 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 prebuild
diff --git a/apps/kb/AGENTS.md b/apps/kb/AGENTS.md
index 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 from
content 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 to
these generated files, one redirect entry per route section (`guides`, `topics`, `troubleshooting`). It also
rewrites 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: text
If 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 guidance
diff --git a/apps/kb/package.json b/apps/kb/package.json
index 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.ts
similarity index 84%
rename from apps/kb/scripts/generate-markdown.test.mjs
rename to apps/kb/scripts/generate-markdown.test.ts
index 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.ts
similarity index 69%
rename from apps/kb/scripts/generate-markdown.mjs
rename to apps/kb/scripts/generate-markdown.ts
index 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.ts
index 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 already
diff --git a/apps/kb/src/lib/topics.ts b/apps/kb/src/lib/topics.ts
index 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 entries
export const isInTopic = ({ collection, topics, topic }: IsInTopicParams): boolean => {
if (collection !== 'troubleshooting') return topics.includes(topic)
// troubleshooting is a content type. other type topics never list it
diff --git a/apps/kb/vercel.json b/apps/kb/vercel.json
index 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.ts
index 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.js
index 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' },