From dfbe20079cc61037c834ba241bb07c55fc834afd Mon Sep 17 00:00:00 2001
From: Jeremias Menichelli <jmenichelli@gmail.com>
Date: Mon, 27 Apr 2026 17:20:32 +0200
Subject: [PATCH] feat: Add support for mdx partials

---
 apps/docs/features/docs/MdxBase.shared.tsx     |  1 -
 apps/docs/scripts/generate-tsdoc-mdx.ts        | 18 +++++++++++++++---
 .../spec/reference/javascript/Auth.partial.mdx |  1 +
 .../reference/javascript/Database.partial.mdx  |  1 +
 .../javascript/introduction.partial.mdx        |  9 +++++++++
 5 files changed, 26 insertions(+), 4 deletions(-)
 create mode 100644 apps/docs/spec/reference/javascript/Auth.partial.mdx
 create mode 100644 apps/docs/spec/reference/javascript/Database.partial.mdx
 create mode 100644 apps/docs/spec/reference/javascript/introduction.partial.mdx

diff --git a/apps/docs/features/docs/MdxBase.shared.tsx b/apps/docs/features/docs/MdxBase.shared.tsx
index e2b8149c096..f076ea7359e 100644
--- a/apps/docs/features/docs/MdxBase.shared.tsx
+++ b/apps/docs/features/docs/MdxBase.shared.tsx
@@ -117,7 +117,6 @@ const components = {
    */
   RefDefinitionParams,
   RefDefinitionReturnType,
-  CodeBlock,
   CollapsibleDetails,
 }
 
diff --git a/apps/docs/scripts/generate-tsdoc-mdx.ts b/apps/docs/scripts/generate-tsdoc-mdx.ts
index b8feb6e8b4c..2aac549f2c8 100644
--- a/apps/docs/scripts/generate-tsdoc-mdx.ts
+++ b/apps/docs/scripts/generate-tsdoc-mdx.ts
@@ -1,4 +1,4 @@
-import { mkdirSync, readdirSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'fs'
 import { join, dirname, relative } from 'path'
 import { fileURLToPath } from 'url'
 import { processSpec, type SpecCategory, type SpecConfig } from './process-tsdoc.js'
@@ -135,7 +135,7 @@ function generateExamplesBlock(examples: any[]): string[] {
   return lines
 }
 
-function generateMdx(categories: SpecCategory[], config: SpecConfig): string {
+function generateMdx(categories: SpecCategory[], config: SpecConfig, specDir: string): string {
   const fmVal = (v: string) => `"${v.replace(/"/g, '\\"')}"`
   const frontmatter = [
     '---',
@@ -151,6 +151,12 @@ function generateMdx(categories: SpecCategory[], config: SpecConfig): string {
   ]
   const lines: string[] = frontmatter
 
+  // Insert optional introduction partial immediately after frontmatter
+  const introParthialPath = join(specDir, 'introduction.partial.mdx')
+  if (existsSync(introParthialPath)) {
+    lines.push(readFileSync(introParthialPath, 'utf-8').trimEnd(), '')
+  }
+
   for (let i = 0; i < categories.length; i++) {
     const { category, definitions } = categories[i]
 
@@ -160,6 +166,12 @@ function generateMdx(categories: SpecCategory[], config: SpecConfig): string {
 
     lines.push(`## ${category}`, '')
 
+    // Insert optional partial: <specDir>/<category-slug>.partial.mdx
+    const partialPath = join(specDir, `${toSlug(category)}.partial.mdx`)
+    if (existsSync(partialPath)) {
+      lines.push(readFileSync(partialPath, 'utf-8').trimEnd(), '')
+    }
+
     for (let j = 0; j < definitions.length; j++) {
       const def = definitions[j]
       const isLastInCategory = j === definitions.length - 1
@@ -221,7 +233,7 @@ for (const specDir of specFolders) {
   mkdirSync(outDir, { recursive: true })
 
   // Write MDX
-  const mdx = generateMdx(categories, config)
+  const mdx = generateMdx(categories, config, specDir)
   const mdxPath = join(outDir, 'index.mdx')
   writeFileSync(mdxPath, mdx)
 
diff --git a/apps/docs/spec/reference/javascript/Auth.partial.mdx b/apps/docs/spec/reference/javascript/Auth.partial.mdx
new file mode 100644
index 00000000000..f5e4aab24b5
--- /dev/null
+++ b/apps/docs/spec/reference/javascript/Auth.partial.mdx
@@ -0,0 +1 @@
+Hello **world**, this is Auth.
\ No newline at end of file
diff --git a/apps/docs/spec/reference/javascript/Database.partial.mdx b/apps/docs/spec/reference/javascript/Database.partial.mdx
new file mode 100644
index 00000000000..a904f7057fe
--- /dev/null
+++ b/apps/docs/spec/reference/javascript/Database.partial.mdx
@@ -0,0 +1 @@
+Hello **world**, this is _Database_.
\ No newline at end of file
diff --git a/apps/docs/spec/reference/javascript/introduction.partial.mdx b/apps/docs/spec/reference/javascript/introduction.partial.mdx
new file mode 100644
index 00000000000..70434bfaac8
--- /dev/null
+++ b/apps/docs/spec/reference/javascript/introduction.partial.mdx
@@ -0,0 +1,9 @@
+### Install
+
+Walla walla...
+
+```sh
+npm i @supabase/supabase-js
+```
+
+Push the tempo.