The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feat(Docs): Add copy as markdown and AI tools to guide (#43355)
Jeremias Menichelli8b4bf646fc96
diff --git a/apps/docs/.gitignore b/apps/docs/.gitignoreindex 55ab4a6d45e..19731c8f0d6 100644--- a/apps/docs/.gitignore+++ b/apps/docs/.gitignore@@ -30,6 +30,8 @@ public/sitemap.xml# llms.txt (generated)public/llms.txtpublic/llms/+# Generated guide markdown files+public/docs/# Copied examples folder/examples/diff --git a/apps/docs/DEVELOPERS.md b/apps/docs/DEVELOPERS.mdindex 2d9f7cb3684..4413ab84577 100644--- a/apps/docs/DEVELOPERS.md+++ b/apps/docs/DEVELOPERS.md@@ -22,6 +22,19 @@ For a complete run-down on how all of our tools work together, see the main DEVE4. Visit http://localhost:3001/docs in your browser - don't forget to append the `/docs` to the end5. Your local site should look exactly like [https://supabase.com/docs](https://supabase.com/docs)+## AI friendly documentation++This project generates Markdown files for each page under `/docs/guides/..` path.++To test locally, within the `apps/docs` directory:++1. Run `pnpm build:guides-markdown`+2. Run `pnpm dev`++This creates Markdown files for all routes under the `public/docs/guides` directory, ignored by Git.++For production this setup runs as a `prebuild` task to allow Vercel to bundle these files with middleware and functions.+## ContributingFor repo organization and style guide, see the [contributing guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md).diff --git a/apps/docs/app/api/guides-md/[...slug]/route.ts b/apps/docs/app/api/guides-md/[...slug]/route.tsnew file mode 100644index 00000000000..f09a7854f25--- /dev/null+++ b/apps/docs/app/api/guides-md/[...slug]/route.ts@@ -0,0 +1,22 @@+import { promises as fs } from 'fs'+import path from 'path'+import { NextResponse } from 'next/server'++export async function GET(_request: Request, { params }: { params: Promise<{ slug: string[] }> }) {+ const { slug } = await params+ const baseDir = path.join(process.cwd(), 'public/docs/guides')+ const filePath = path.join(baseDir, `${slug.join('/')}.md`)++ if (!filePath.startsWith(baseDir + path.sep) && filePath !== baseDir) {+ return new NextResponse('Not found', { status: 404 })+ }++ try {+ const content = await fs.readFile(filePath, 'utf-8')+ return new NextResponse(content, {+ headers: { 'Content-Type': 'text/markdown; charset=utf-8' },+ })+ } catch {+ return new NextResponse('Not found', { status: 404 })+ }+}diff --git a/apps/docs/app/guides/local-development/cli/config/page.tsx b/apps/docs/app/guides/local-development/cli/config/page.tsxindex 9ce99b1da78..341d800b6f8 100644--- a/apps/docs/app/guides/local-development/cli/config/page.tsx+++ b/apps/docs/app/guides/local-development/cli/config/page.tsx@@ -1,7 +1,7 @@import ReactMarkdown from 'react-markdown'import { CodeBlock } from 'ui'import { Heading } from 'ui/src/components/CustomHTMLElements'-import { type TOCHeader } from '~/components/GuidesTableOfContents'+import { type TOCHeader } from '~/components/GuidesSidebar'import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'import { GuideTemplate, newEditLink } from '~/features/docs/GuidesMdx.template'import type { Parameter } from '~/lib/refGenerator/refTypes'diff --git a/apps/docs/components/GuidesSidebar.tsx b/apps/docs/components/GuidesSidebar.tsxnew file mode 100644index 00000000000..ee4e8c49b4b--- /dev/null+++ b/apps/docs/components/GuidesSidebar.tsx@@ -0,0 +1,134 @@+'use client'++import { Check, Copy, ExternalLink } from 'lucide-react'+import { usePathname } from 'next/navigation'+import { useState } from 'react'+import { isFeatureEnabled } from 'common'+import { cn } from 'ui'+import { ExpandableVideo } from 'ui-patterns/ExpandableVideo'+import { Toc, TOCItems, TOCScrollArea } from 'ui-patterns/Toc'+import { Feedback } from '~/components/Feedback'+import { useTocAnchors } from '../features/docs/GuidesMdx.state'++interface TOCHeader {+ id?: string+ text: string+ link: string+ level: number+}++function AiTools({ className }: { className?: string }) {+ const [copied, setCopied] = useState(false)+ let url = ''++ // Safe check for server side rendering.+ try {+ const urlParts = new URL(`${window.location}`)+ url = urlParts.origin + urlParts.pathname+ } catch (error) {}++ async function copyMarkdown() {+ const mdUrl = `${url}.md`++ try {+ const res = await fetch(mdUrl)+ const text = await res.text()+ await navigator.clipboard.writeText(text)+ setCopied(true)+ setTimeout(() => setCopied(false), 2000)+ } catch (error) {+ console.error('Failed to copy markdown', error)+ }+ }++ return (+ <section className={cn(className)} aria-labelledby="ask-ai-title">+ <h3+ id="ask-ai-title"+ className="block font-mono uppercase text-xs text-foreground-light mb-3"+ >+ AI Tools+ </h3>+ <div className="flex flex-col gap-2">+ <button+ onClick={copyMarkdown}+ className="flex items-center gap-1.5 text-xs text-foreground-lighter hover:text-foreground text-left transition-colors"+ >+ {copied ? (+ <Check size={14} strokeWidth={1.5} className="text-brand" />+ ) : (+ <Copy size={14} strokeWidth={1.5} />+ )}+ {copied ? 'Copied!' : 'Copy as Markdown'}+ </button>+ <a+ href={`https://chatgpt.com/?hint=search&q=Read from ${url} so I can ask questions about its contents`}+ target="_blank"+ rel="noreferrer noopener"+ className="flex items-center gap-1.5 text-xs text-foreground-lighter hover:text-foreground transition-colors"+ >+ <ExternalLink size={14} strokeWidth={1.5} />+ Ask ChatGPT+ </a>+ <a+ href={`https://claude.ai/new?q=Read from ${url} so I can ask questions about its contents`}+ target="_blank"+ rel="noreferrer noopener"+ className="flex items-center gap-1.5 text-xs text-foreground-lighter hover:text-foreground transition-colors"+ >+ <ExternalLink size={14} strokeWidth={1.5} />+ Ask Claude+ </a>+ </div>+ </section>+ )+}++const GuidesSidebar = ({+ className,+ video,+ hideToc,+}: {+ className?: string+ video?: string+ hideToc?: boolean+}) => {+ const pathname = usePathname()+ const { toc } = useTocAnchors()+ const showFeedback = isFeatureEnabled('feedback:docs')+ const tocVideoPreview = `https://img.youtube.com/vi/${video}/0.jpg`++ return (+ <div className={cn('thin-scrollbar overflow-y-auto h-fit', 'px-px', className)}>+ <div className="w-full relative border-l flex flex-col gap-6 lg:gap-8 px-2 h-fit">+ {video && (+ <div className="relative pl-5">+ <ExpandableVideo imgUrl={tocVideoPreview} videoId={video} />+ </div>+ )}+ {showFeedback && (+ <div className="pl-5">+ <Feedback key={pathname} />+ </div>+ )}+ <div className="pl-5">+ <AiTools key={pathname} />+ </div>+ {!hideToc && toc.length !== 0 && (+ <Toc className="-ml-[calc(0.25rem+6px)]">+ <h3 className="inline-flex items-center gap-1.5 font-mono text-xs uppercase text-foreground pl-[calc(1.5rem+6px)]">+ On this page+ </h3>+ <TOCScrollArea>+ <TOCItems items={toc} />+ </TOCScrollArea>+ </Toc>+ )}+ </div>+ </div>+ )+}++export default GuidesSidebar+export { GuidesSidebar }+export type { TOCHeader }diff --git a/apps/docs/components/GuidesTableOfContents.tsx b/apps/docs/components/GuidesTableOfContents.tsxdeleted file mode 100644index ebb1fd4158f..00000000000--- a/apps/docs/components/GuidesTableOfContents.tsx+++ /dev/null@@ -1,55 +0,0 @@-'use client'--import { usePathname } from 'next/navigation'-import { isFeatureEnabled } from 'common'-import { cn } from 'ui'-import { ExpandableVideo } from 'ui-patterns/ExpandableVideo'-import { Toc, TOCItems, TOCScrollArea } from 'ui-patterns/Toc'-import { Feedback } from '~/components/Feedback'-import { useTocAnchors } from '../features/docs/GuidesMdx.state'--interface TOCHeader {- id?: string- text: string- link: string- level: number-}--const GuidesTableOfContents = ({ className, video }: { className?: string; video?: string }) => {- const pathname = usePathname()- const { toc } = useTocAnchors()-- const showFeedback = isFeatureEnabled('feedback:docs')-- const tocVideoPreview = `https://img.youtube.com/vi/${video}/0.jpg`-- return (- <div className={cn('thin-scrollbar overflow-y-auto h-fit', 'px-px', className)}>- <div className="w-full relative border-l flex flex-col gap-6 lg:gap-8 px-2 h-fit">- {video && (- <div className="relative pl-5">- <ExpandableVideo imgUrl={tocVideoPreview} videoId={video} />- </div>- )}- {showFeedback && (- <div className="pl-5">- <Feedback key={pathname} />- </div>- )}- {toc.length !== 0 && (- <Toc className="-ml-[calc(0.25rem+6px)]">- <h3 className="inline-flex items-center gap-1.5 font-mono text-xs uppercase text-foreground pl-[calc(1.5rem+6px)]">- On this page- </h3>- <TOCScrollArea>- <TOCItems items={toc} />- </TOCScrollArea>- </Toc>- )}- </div>- </div>- )-}--export default GuidesTableOfContents-export type { TOCHeader }diff --git a/apps/docs/features/docs/GuidesMdx.template.tsx b/apps/docs/features/docs/GuidesMdx.template.tsxindex 76fbe6d397c..97758032965 100644--- a/apps/docs/features/docs/GuidesMdx.template.tsx+++ b/apps/docs/features/docs/GuidesMdx.template.tsx@@ -5,7 +5,7 @@ import ReactMarkdown from 'react-markdown'import { cn } from 'ui'import Breadcrumbs from '~/components/Breadcrumbs'-import GuidesTableOfContents from '~/components/GuidesTableOfContents'+import GuidesSidebar from '~/components/GuidesSidebar'import { TocAnchorsProvider } from '~/features/docs/GuidesMdx.client'import { MDXRemoteBase } from '~/features/docs/MdxBase'import type { WithRequired } from '~/features/helpers.types'@@ -71,7 +71,7 @@ const GuideTemplate = ({ meta, content, children, editLink, mdxOptions }: GuideT'relative','transition-all ease-out','duration-100',- hideToc ? 'col-span-12' : 'col-span-12 md:col-span-9'+ 'col-span-12 md:col-span-9')}><Breadcrumbs className="mb-2" />@@ -114,24 +114,23 @@ const GuideTemplate = ({ meta, content, children, editLink, mdxOptions }: GuideT</footer></article></div>- {!hideToc && (- <GuidesTableOfContents- video={meta?.tocVideo}- className={cn(- 'hidden md:flex',- 'col-span-3 self-start',- 'sticky',- /**- * --header-height: height of nav- * 1px: height of nav border- * 2rem: content padding- */- 'top-[calc(var(--header-height)+1px+2rem)]',- // 3rem accounts for 2rem of top padding + 1rem of extra breathing room- 'max-h-[calc(100vh-var(--header-height)-3rem)]'- )}- />- )}+ <GuidesSidebar+ video={meta?.tocVideo}+ hideToc={hideToc}+ className={cn(+ 'hidden md:flex',+ 'col-span-3 self-start',+ 'sticky',+ /**+ * --header-height: height of nav+ * 1px: height of nav border+ * 2rem: content padding+ */+ 'top-[calc(var(--header-height)+1px+2rem)]',+ // 3rem accounts for 2rem of top padding + 1rem of extra breathing room+ 'max-h-[calc(100vh-var(--header-height)-3rem)]'+ )}+ /></div></TocAnchorsProvider>)diff --git a/apps/docs/features/ui/guide/Guide.tsx b/apps/docs/features/ui/guide/Guide.tsxindex e0179dd7ab3..9fa9b8c31c3 100644--- a/apps/docs/features/ui/guide/Guide.tsx+++ b/apps/docs/features/ui/guide/Guide.tsx@@ -3,7 +3,7 @@import { createContext, useContext, type ReactNode } from 'react'import { cn } from 'ui'-import GuidesTableOfContents from '~/components/GuidesTableOfContents'+import GuidesTableOfContents from '~/components/GuidesSidebar'import { TocAnchorsProvider } from '~/features/docs/GuidesMdx.client'import { type GuideFrontmatter } from '~/lib/docs'diff --git a/apps/docs/internals/generate-guides-markdown.ts b/apps/docs/internals/generate-guides-markdown.tsnew file mode 100644index 00000000000..c07cb27bcb2--- /dev/null+++ b/apps/docs/internals/generate-guides-markdown.ts@@ -0,0 +1,165 @@+import fs from 'fs'+import path from 'path'+import { globby } from 'globby'+import matter from 'gray-matter'++const PARTIALS_DIR = path.join(process.cwd(), 'content', '_partials')++/**+ * Reads <$Partial path="..." /> tags and replaces them with the file contents.+ * Recurses to handle nested partials.+ */+async function inlinePartials(content: string): Promise<string> {+ const partialRegex = /<\$Partial\s+path="([^"]+)"[^/]*\/>/g+ const matches = [...content.matchAll(partialRegex)]+ for (const [fullMatch, partialPath] of matches) {+ try {+ const raw = await fs.promises.readFile(path.join(PARTIALS_DIR, partialPath), 'utf8')+ const { content: partialBody } = matter(raw)+ const inlined = await inlinePartials(partialBody)+ content = content.replace(fullMatch, inlined)+ } catch {+ content = content.replace(fullMatch, '')+ }+ }+ return content+}++/** Remove the minimum common leading whitespace from all non-empty lines. */+function dedentBlock(text: string): string {+ const lines = text.split('\n')+ const nonEmpty = lines.filter((l) => /\S/.test(l))+ if (!nonEmpty.length) return text+ const minIndent = Math.min(...nonEmpty.map((l) => (l.match(/^([ \t]*)/) ?? ['', ''])[1].length))+ if (!minIndent) return text+ return lines.map((l) => l.slice(minIndent)).join('\n')+}++/**+ * Converts StepHikeCompact components to markdown ordered lists.+ * Each step becomes a numbered item: the title (from Details) is bolded on the item+ * line, and the full step body (Details + Code) is dedented and appended below.+ * Remaining JSX tags inside the body are later stripped by stripJsxTags.+ */+function convertStepHike(content: string): string {+ return content.replace(/<StepHikeCompact>([\s\S]*?)<\/StepHikeCompact>/g, (_, body) => {+ const items: string[] = []+ const stepRe = /<StepHikeCompact\.Step[^>]*>([\s\S]*?)<\/StepHikeCompact\.Step>/g+ let stepNum = 1+ let m: RegExpExecArray | null+ while ((m = stepRe.exec(body)) !== null) {+ const stepBody = m[1]+ const titleMatch = stepBody.match(/<StepHikeCompact\.Details[^>]+title="([^"]*)"/)+ const title = titleMatch ? titleMatch[1] : ''+ // Dedent the entire step body so nested JSX indentation is removed.+ // Remaining component tags (Details, Code, Admonition…) are stripped later.+ const inner = dedentBlock(stepBody).trim()+ const item = title ? `${stepNum}. **${title}**\n\n${inner}` : `${stepNum}. ${inner}`+ items.push(item)+ stepNum+++ }+ return items.join('\n\n')+ })+}++/**+ * Strips JSX component tags (capitalized names, dot-notation, or $-prefixed)+ * while keeping their inner content. Also strips wrapper div and a elements.+ * Removes MDX JSX comment blocks. Strips unnecessary leading indentation from+ * non-code-block lines.+ */+function stripJsxTags(content: string): string {+ // Remove MDX/JSX comments {/* ... */}+ content = content.replace(/\{\/\*[\s\S]*?\*\/\}/g, '')++ // Remove self-closing JSX components: <Component ... /> or <$Directive ... />+ content = content.replace(/<[\$A-Z][\w.]*(?:\s[^>]*)?\s*\/>/gs, '')++ // Remove opening JSX component tags (possibly multi-line): <Component ...>+ content = content.replace(/<[\$A-Z][\w.]*(?:\s[^>]*)?\s*>/gs, '')++ // Remove closing JSX component tags: </Component>+ content = content.replace(/<\/[\$A-Z][\w.]*>/g, '')++ // Remove wrapper div and a elements used structurally in MDX (carry JSX props+ // like className which are not valid HTML; inner content such as img is preserved)+ content = content.replace(/<div(?:\s[^>]*)?\s*>/g, '')+ content = content.replace(/<\/div>/g, '')+ content = content.replace(/<a(?:\s[^>]*)?\s*>/g, '')+ content = content.replace(/<\/a>/g, '')++ // Split on fenced code blocks to handle prose and code separately.+ // For prose (even segments): strip leading whitespace (removes JSX nesting indent).+ // For code blocks (odd segments): dedent the body to remove JSX nesting indent while+ // preserving relative code structure, then normalize the closing fence.+ const segments = content.split(/(```[\s\S]*?```)/g)+ content = segments+ .map((seg, i) => {+ if (i % 2 === 0) return seg.replace(/^[ \t]+/gm, '')+ return seg.replace(+ /^(```[^\n]*\n)([\s\S]*?)(\n[ \t]*```)$/,+ (_, open, body) => open + dedentBlock(body) + '\n```'+ )+ })+ .join('')++ // Collapse lines that are only whitespace to empty lines, then deduplicate blank lines+ content = content.replace(/^[^\S\n]+$/gm, '')+ content = content.replace(/\n{3,}/g, '\n\n').trim()++ return content+}++async function generate() {+ const files = await globby(['content/guides/**/!(_)*.mdx'])+ let warnings = 0++ await Promise.all(+ files.map(async (filePath) => {+ const outPath = filePath+ .replace(/^content\/guides\//, 'public/docs/guides/')+ .replace(/\.mdx$/, '.md')++ let output: string+ try {+ const raw = await fs.promises.readFile(filePath, 'utf8')+ const { content: rawContent, data } = matter(raw)++ const withPartials = await inlinePartials(rawContent)+ const withSteps = convertStepHike(withPartials)+ const processed = stripJsxTags(withSteps)++ const header = [+ data.title ? `# ${data.title}` : '',+ data.subtitle || data.description ? `\n${data.subtitle ?? data.description}` : '',+ ]+ .filter(Boolean)+ .join('\n')++ output = header ? `${header}\n\n${processed}` : processed+ } catch (err) {+ warnings+++ console.warn(+ `[warn] Failed to process ${filePath}: ${err instanceof Error ? err.message : err}`+ )+ // Fall back to raw file content so the route still serves something+ try {+ output = await fs.promises.readFile(filePath, 'utf8')+ } catch {+ output = `<!-- failed to generate: ${filePath} -->`+ }+ }++ // content/guides/ai/vector-columns.mdx → public/docs/guides/ai/vector-columns.md+ // Placing under public/docs/ ensures the file is served at /docs/guides/...+ // matching the exact URL of the rendered page.+ await fs.promises.mkdir(path.dirname(outPath), { recursive: true })+ await fs.promises.writeFile(outPath, output)+ })+ )++ const summary = warnings ? ` (${warnings} with warnings)` : ''+ console.log(`Generated ${files.length} markdown files under public/docs/guides/${summary}`)+}++generate()diff --git a/apps/docs/middleware.ts b/apps/docs/middleware.tsindex ea55aafa52e..27868037dee 100644--- a/apps/docs/middleware.ts+++ b/apps/docs/middleware.ts@@ -6,8 +6,19 @@ import { BASE_PATH } from '~/lib/constants'const REFERENCE_PATH = `${BASE_PATH ?? ''}/reference`+const GUIDES_PATH = `${BASE_PATH ?? ''}/guides`+export function middleware(request: NextRequest) {const url = new URL(request.url)++ // Serve pre-generated .md files before the [[...slug]] page route can intercept them+ if (url.pathname.startsWith(GUIDES_PATH + '/') && url.pathname.endsWith('.md')) {+ const slug = url.pathname.slice(GUIDES_PATH.length + 1, -'.md'.length)+ const rewriteUrl = new URL(url)+ rewriteUrl.pathname = `${BASE_PATH ?? ''}/api/guides-md/${slug}`+ return NextResponse.rewrite(rewriteUrl)+ }+if (!url.pathname.startsWith(REFERENCE_PATH)) {return NextResponse.next()}@@ -56,5 +67,5 @@ export function middleware(request: NextRequest) {}export const config = {- matcher: '/reference/:path*',+ matcher: ['/reference/:path*', '/guides/:path*'],}diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjsindex d1419a3e104..53e8066039e 100644--- a/apps/docs/next.config.mjs+++ b/apps/docs/next.config.mjs@@ -60,6 +60,7 @@ const nextConfig = {],outputFileTracingIncludes: {'/api/crawlers': ['./features/docs/generated/**/*', './docs/ref/**/*'],+ '/api/guides-md/**/*': ['./public/docs/guides/**/*'],'/guides/**/*': ['./content/guides/**/*', './content/troubleshooting/**/*', './examples/**/*'],'/reference/**/*': ['./features/docs/generated/**/*', './docs/ref/**/*'],},diff --git a/apps/docs/package.json b/apps/docs/package.jsonindex 98acb87d8d3..1f562c8413e 100644--- a/apps/docs/package.json+++ b/apps/docs/package.json@@ -7,6 +7,7 @@"build": "next build","build:analyze": "ANALYZE=true next build","build:llms": "tsx --conditions=react-server ./scripts/llms.ts",+ "build:guides-markdown": "tsx ./internals/generate-guides-markdown.ts","build:sitemap": "tsx ./internals/generate-sitemap.ts","clean": "rimraf .next .turbo node_modules features/docs/generated examples __generated__","codegen:examples": "shx cp -r ../../examples ./examples",@@ -25,7 +26,7 @@"lint": "eslint .","lint:mdx": "supa-mdx-lint content --config ../../supa-mdx-lint.config.toml","postbuild": "pnpm run build:sitemap && pnpm run build:llms && ./../../scripts/upload-static-assets.sh",- "prebuild": "pnpm run codegen:graphql && pnpm run codegen:references && pnpm run codegen:examples",+ "prebuild": "pnpm run codegen:graphql && pnpm run codegen:references && pnpm run codegen:examples && pnpm run build:guides-markdown","predev": "pnpm run codegen:graphql && pnpm run codegen:references && pnpm run codegen:examples","preembeddings": "pnpm run codegen:references","preinstall": "npx only-allow pnpm",