From 10df98f2d5028000343d616da4dfd67cecbf9bc8 Mon Sep 17 00:00:00 2001
From: Jeremias Menichelli <jmenichelli@gmail.com>
Date: Mon, 7 Sep 2026 16:00:29 +0200
Subject: [PATCH] feat(kb): Create homepage and pinned topics and guides
 (#49999)

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Adding the ability to pin guides or specific topics to homepage.

_To test:_
 - Enter the preview of the project
 - Go to the homepage
- Make sure pinned topics, pinned guides and the rest of the links work
correctly.

 _Screenshot_

<img width="894" height="3772" alt="Screenshot 2026-09-04 at 12-12-37
Home Supabase Knowledge Base"
src="https://github.com/user-attachments/assets/a1b33e1b-bcbf-43db-b453-64fc1a0c9a00"
/>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **New Features**
- Added homepage sections for pinned topics, featured guides, all
guides, and all topics.
- Added reusable cards with titles, descriptions, topic badges, and
optional links.
- Added support for GitHub-style Markdown alerts, including notes, tips,
warnings, and cautions.
- Added the ability to mark guides and topics as pinned for homepage
featuring.
  - Added a guide demonstrating supported alert styles.

- **Style**
- Improved header, hero, and card borders for a more consistent visual
treatment.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/kb/src/components/Card.astro          | 45 ++++++++++++++
 apps/kb/src/components/Header.tsx          |  2 +-
 apps/kb/src/components/Hero.tsx            |  2 +-
 apps/kb/src/content.config.ts              |  2 +
 apps/kb/src/content/guides/sample-guide.md |  1 +
 apps/kb/src/lib/topics.ts                  | 46 ++++++++++----
 apps/kb/src/pages/index.astro              | 71 ++++++++++++++++++++++
 7 files changed, 156 insertions(+), 13 deletions(-)
 create mode 100644 apps/kb/src/components/Card.astro

diff --git a/apps/kb/src/components/Card.astro b/apps/kb/src/components/Card.astro
new file mode 100644
index 00000000000..8784427734e
--- /dev/null
+++ b/apps/kb/src/components/Card.astro
@@ -0,0 +1,45 @@
+---
+// Small "glass panel" card, adapted from apps/docs' GlassPanel
+// (packages/ui-patterns/src/GlassPanel/index.tsx) — same surface treatment
+// (bg-surface-75, hover:border-strong), trimmed to what kb needs: no
+// logo/icon-picker machinery, which pulled in next/image and next-themes
+// that don't apply to a plain Astro app.
+//
+// Unlike GlassPanel (always a plain <div>, link-agnostic — every call site
+// in docs wraps it in a Next.js <Link>), this renders as an <a> itself when
+// `href` is given. That's only safe because `topics` render as plain,
+// non-linked badges — nothing inside the card is itself a link, so there's
+// no nested-<a> problem.
+import { Badge } from 'ui'
+
+interface Props {
+	href?: string
+	title: string
+	description?: string
+	topics?: string[]
+	class?: string
+}
+
+const { href, title, description, topics = [], class: className } = Astro.props
+const Tag = href ? 'a' : 'div'
+---
+
+<Tag
+	href={href}
+	class:list={[
+		'relative flex h-full flex-col gap-2 rounded-lg border border-default bg-surface-75 p-5 text-left transition hover:border-strong',
+		className,
+	]}
+>
+	<h2 class="m-0 text-base font-medium text-foreground">{title}</h2>
+	{description && <p class="m-0 text-sm text-foreground-light">{description}</p>}
+	{
+		topics.length > 0 && (
+			<div class="mt-2 flex flex-wrap gap-2">
+				{topics.map((topic) => (
+					<Badge>{topic}</Badge>
+				))}
+			</div>
+		)
+	}
+</Tag>
diff --git a/apps/kb/src/components/Header.tsx b/apps/kb/src/components/Header.tsx
index 5f7c344da07..f1b9c746a54 100644
--- a/apps/kb/src/components/Header.tsx
+++ b/apps/kb/src/components/Header.tsx
@@ -7,7 +7,7 @@ import { ThemeToggle } from './ThemeToggle'
 // search, no user menu, no dashboard link — kb doesn't have any of that yet.
 function Header() {
   return (
-    <header className="backdrop-blur-sm backdrop-filter bg-default/75 border-b w-full px-5 lg:pl-10 items-center flex h-(--header-height) gap-3">
+    <header className="backdrop-blur-sm backdrop-filter bg-default/75 border-b border-default w-full px-5 lg:pl-10 items-center flex h-(--header-height) gap-3">
       <div className="flex basis-full h-full items-center justify-center gap-2">
         <Logo />
         <Nav />
diff --git a/apps/kb/src/components/Hero.tsx b/apps/kb/src/components/Hero.tsx
index 8da35007604..779eac3e08b 100644
--- a/apps/kb/src/components/Hero.tsx
+++ b/apps/kb/src/components/Hero.tsx
@@ -3,7 +3,7 @@
 // prompt panel (docs-specific, feature-flagged, and not something kb has yet).
 function Hero() {
   return (
-    <div className="w-full border-b bg-muted/10">
+    <div className="w-full border-b border-default bg-muted/10">
       <div className="mx-auto max-w-7xl px-6 py-16">
         <h1 className="m-0 text-3xl text-foreground sm:text-4xl">Supabase Knowledge Base</h1>
         <p className="m-0 mt-2 text-base leading-7 text-foreground-light sm:mt-3 sm:text-xl">
diff --git a/apps/kb/src/content.config.ts b/apps/kb/src/content.config.ts
index fec50c46fb6..245e1163529 100644
--- a/apps/kb/src/content.config.ts
+++ b/apps/kb/src/content.config.ts
@@ -15,6 +15,8 @@ const guides = defineCollection({
     // z.enum (not z.string) so a guide referencing a topic outside TOPICS
     // fails content validation instead of silently rendering an orphaned tag.
     topics: z.array(z.enum(TOPIC_NAMES)),
+    // Surfaces the guide in the homepage's "Featured Guides" section.
+    pinned: z.boolean().default(false),
     github_url: z.string().optional(),
   }),
 })
diff --git a/apps/kb/src/content/guides/sample-guide.md b/apps/kb/src/content/guides/sample-guide.md
index f1af5d55b00..7aa9a1f9a8c 100644
--- a/apps/kb/src/content/guides/sample-guide.md
+++ b/apps/kb/src/content/guides/sample-guide.md
@@ -2,6 +2,7 @@
 title: 'Markdown elements sample'
 description: 'A lorem ipsum sample guide exercising every base Markdown element supported by the guide layout.'
 topics: ['Tutorial', 'Database']
+pinned: true
 github_url: 'https://github.com/supabase/supabase/discussions/0000000'
 ---
 
diff --git a/apps/kb/src/lib/topics.ts b/apps/kb/src/lib/topics.ts
index c0725d4a303..ecfe5e9c764 100644
--- a/apps/kb/src/lib/topics.ts
+++ b/apps/kb/src/lib/topics.ts
@@ -1,18 +1,42 @@
 // Canonical list of guide topics. Single source of truth for the `topics`
 // field in src/content.config.ts (so a guide with an unsupported topic fails
 // content validation), the "Topics" nav menu, and the /topics/[topic] pages.
+//
+// `pinned` topics surface as cards on the homepage (see src/pages/index.astro)
+// — keep this to a handful so that section stays a highlights row, not a
+// second copy of the full topic list.
 export const TOPICS = [
-  { name: 'Migration', description: 'Moving data, schemas, or projects onto Supabase' },
-  { name: 'Comparison', description: 'How Supabase compares to other databases and platforms' },
-  { name: 'Troubleshooting', description: 'Common errors and how to resolve them' },
-  { name: 'Tutorial', description: 'Step-by-step walkthroughs for building with Supabase' },
-  { name: 'Storage', description: 'Uploading, managing, and serving files' },
-  { name: 'Auth', description: 'Authentication, authorization, and user management' },
-  { name: 'Database', description: 'Postgres schemas, queries, and performance' },
-  { name: 'Edge Functions', description: 'Deploying and running serverless functions' },
-  { name: 'Queues', description: 'Background jobs and message processing' },
-  { name: 'Realtime', description: 'Broadcast, presence, and database changes' },
-  { name: 'Supabase Platform', description: 'Project settings, billing, and infrastructure' },
+  {
+    name: 'Migration',
+    description: 'Moving data, schemas, or projects onto Supabase',
+    pinned: false,
+  },
+  {
+    name: 'Comparison',
+    description: 'How Supabase compares to other databases and platforms',
+    pinned: false,
+  },
+  { name: 'Troubleshooting', description: 'Common errors and how to resolve them', pinned: false },
+  {
+    name: 'Tutorial',
+    description: 'Step-by-step walkthroughs for building with Supabase',
+    pinned: true,
+  },
+  { name: 'Storage', description: 'Uploading, managing, and serving files', pinned: false },
+  { name: 'Auth', description: 'Authentication, authorization, and user management', pinned: true },
+  { name: 'Database', description: 'Postgres schemas, queries, and performance', pinned: true },
+  {
+    name: 'Edge Functions',
+    description: 'Deploying and running serverless functions',
+    pinned: false,
+  },
+  { name: 'Queues', description: 'Background jobs and message processing', pinned: false },
+  { name: 'Realtime', description: 'Broadcast, presence, and database changes', pinned: false },
+  {
+    name: 'Supabase Platform',
+    description: 'Project settings, billing, and infrastructure',
+    pinned: false,
+  },
 ] as const
 
 export type Topic = (typeof TOPICS)[number]['name']
diff --git a/apps/kb/src/pages/index.astro b/apps/kb/src/pages/index.astro
index fe909f38c65..0ad77523149 100644
--- a/apps/kb/src/pages/index.astro
+++ b/apps/kb/src/pages/index.astro
@@ -1,8 +1,79 @@
 ---
+import { getCollection } from 'astro:content'
+
+import Card from '../components/Card.astro'
 import { Hero } from '../components/Hero'
 import Layout from '../layouts/Layout.astro'
+import { TOPICS, topicToSlug } from '../lib/topics'
+
+const guides = await getCollection('guides')
+const pinnedTopics = TOPICS.filter((topic) => topic.pinned)
+const featuredGuides = guides.filter((guide) => guide.data.pinned)
 ---
 
 <Layout title="Home" description="In-depth guides, tutorials, and explainers for best practices for Supabase databases.">
 	<Hero />
+
+	<div class="mx-auto flex max-w-7xl flex-col gap-16 px-6 py-16">
+		{
+			pinnedTopics.length > 0 && (
+				<section class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+					{pinnedTopics.map((topic) => (
+						<Card
+							href={`${import.meta.env.BASE_URL}/topics/${topicToSlug(topic.name)}`}
+							title={topic.name}
+							description={topic.description}
+						/>
+					))}
+				</section>
+			)
+		}
+
+		{
+			featuredGuides.length > 0 && (
+				<section>
+					<h2 class="mb-6 text-2xl font-medium text-foreground">Featured Guides</h2>
+					<div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+						{featuredGuides.map((guide) => (
+							<Card
+								href={`${import.meta.env.BASE_URL}/guides/${guide.id}`}
+								title={guide.data.title}
+								description={guide.data.description}
+								topics={guide.data.topics}
+							/>
+						))}
+					</div>
+				</section>
+			)
+		}
+
+		<section>
+			<h2 class="mb-6 text-2xl font-medium text-foreground">All Guides</h2>
+			<ul class="flex flex-col gap-2">
+				{guides.map((guide) => (
+					<li>
+						<a href={`${import.meta.env.BASE_URL}/guides/${guide.id}`} class="text-brand-link hover:underline">
+							{guide.data.title}
+						</a>
+					</li>
+				))}
+			</ul>
+		</section>
+
+		<section>
+			<h2 class="mb-6 text-2xl font-medium text-foreground">All Topics</h2>
+			<ul class="flex flex-col gap-2">
+				{TOPICS.map((topic) => (
+					<li>
+						<a
+							href={`${import.meta.env.BASE_URL}/topics/${topicToSlug(topic.name)}`}
+							class="text-brand-link hover:underline"
+						>
+							{topic.name}
+						</a>
+					</li>
+				))}
+			</ul>
+		</section>
+	</div>
 </Layout>