Skip to content

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

feat(docs): show guides sidebar on Management API introduction

Johan Bergströma58bb832c62a
diff --git a/apps/docs/docs/ref/api/introduction.mdx b/apps/docs/docs/ref/api/introduction.mdx
index 6f005cda88a..21e33affa4d 100644
--- a/apps/docs/docs/ref/api/introduction.mdx
+++ b/apps/docs/docs/ref/api/introduction.mdx
@@ -2,6 +2,13 @@
id: introduction
title: introduction
hideTitle: true
+links:
+ - title: OpenAPI Docs
+ href: https://api.supabase.com/api/v1
+ - title: OpenAPI Spec
+ href: https://api.supabase.com/api/v1-json
+ - title: Report bugs and issues
+ href: https://github.com/supabase/supabase
---
<div className="flex items-start gap-6 not-prose" id="introduction">
@@ -10,8 +17,7 @@ hideTitle: true
</div>
</div>
-<RefSubLayout.EducationRow>
- <RefSubLayout.Details>
+<RefSubLayout.Details>
Manage your Supabase organizations and projects programmatically.
@@ -42,16 +48,4 @@ hideTitle: true
The Management API is subject to our fair-use policy. All resources created via the API are subject to the pricing detailed on our [Pricing](https://supabase.com/pricing) pages.
- </RefSubLayout.Details>
-
- <RefSubLayout.Examples>
-
- Additional links
-
- - [OpenAPI Docs](https://api.supabase.com/api/v1)
- - [OpenAPI Spec](https://api.supabase.com/api/v1-json)
- - [Report bugs and issues](https://github.com/supabase/supabase)
-
- </RefSubLayout.Examples>
-
- </RefSubLayout.EducationRow>
+</RefSubLayout.Details>
diff --git a/apps/docs/features/docs/Reference.apiPage.tsx b/apps/docs/features/docs/Reference.apiPage.tsx
index e8344cb3a85..f0dadbdf53a 100644
--- a/apps/docs/features/docs/Reference.apiPage.tsx
+++ b/apps/docs/features/docs/Reference.apiPage.tsx
@@ -1,13 +1,20 @@
-import { notFound, redirect } from 'next/navigation'
-
import { MenuId } from '~/components/Navigation/NavigationMenu/NavigationMenu'
import { reference_api } from '~/components/Navigation/NavigationMenu/NavigationMenu.constants'
+import { TocAnchorsProvider } from '~/features/docs/GuidesMdx.client'
import { getSectionsBySlug } from '~/features/docs/Reference.generated.singleton'
+import { getRefFrontmatter } from '~/features/docs/Reference.mdx'
import { ReferenceNavigation } from '~/features/docs/Reference.navigation'
import { ReferenceContentScrollHandler } from '~/features/docs/Reference.navigation.client'
import { SectionSwitch } from '~/features/docs/Reference.sections'
+import {
+ ReferenceLinks,
+ ReferenceSidebar,
+ type ReferenceLink,
+} from '~/features/docs/Reference.sidebar'
import { LayoutMainContent } from '~/layouts/DefaultLayout'
import { SidebarSkeleton } from '~/layouts/MainSkeleton'
+import { notFound, redirect } from 'next/navigation'
+import { cn } from 'ui'
export async function ApiReferencePage({ path }: { path: Array<string> }) {
const operationSlug = path[0]
@@ -27,6 +34,11 @@ async function ApiOperationPage({ operationSlug }: { operationSlug: string }) {
const section = sectionsBySlug?.get(operationSlug)
if (!section) notFound()
+ const isIntroduction = section.type === 'markdown'
+ const additionalLinks = isIntroduction
+ ? (((await getRefFrontmatter(`api/${section.id}`)).links as ReferenceLink[] | undefined) ?? [])
+ : []
+
return (
<ReferenceContentScrollHandler libPath="api" version="latest" isLatestVersion={true}>
<SidebarSkeleton
@@ -44,9 +56,36 @@ async function ApiOperationPage({ operationSlug }: { operationSlug: string }) {
}
>
<LayoutMainContent>
- <article className="@container/article">
- <SectionSwitch libraryId="api" version="latest" section={section} />
- </article>
+ {isIntroduction ? (
+ <TocAnchorsProvider>
+ <div className="grid grid-cols-12 relative gap-4">
+ <article
+ // Used to get headings for the table of contents
+ id="sb-docs-guide-main-article"
+ className="@container/article col-span-12 md:col-span-8 min-w-0"
+ >
+ <SectionSwitch libraryId="api" version="latest" section={section} />
+ {/* The sidebar is hidden below `md`, so keep the links reachable */}
+ {additionalLinks.length !== 0 && (
+ <ReferenceLinks links={additionalLinks} className="mt-8 md:hidden" />
+ )}
+ </article>
+ <ReferenceSidebar
+ links={additionalLinks}
+ className={cn(
+ 'hidden md:flex md:col-span-3 md:col-start-10',
+ 'self-start sticky',
+ 'top-[calc(var(--header-height)+3rem)]',
+ 'max-h-[calc(100vh-var(--header-height)-4rem)]'
+ )}
+ />
+ </div>
+ </TocAnchorsProvider>
+ ) : (
+ <article className="@container/article">
+ <SectionSwitch libraryId="api" version="latest" section={section} />
+ </article>
+ )}
</LayoutMainContent>
</SidebarSkeleton>
</ReferenceContentScrollHandler>
diff --git a/apps/docs/features/docs/Reference.mdx.tsx b/apps/docs/features/docs/Reference.mdx.tsx
index 2f3f846c9f9..b2600aa2795 100644
--- a/apps/docs/features/docs/Reference.mdx.tsx
+++ b/apps/docs/features/docs/Reference.mdx.tsx
@@ -11,7 +11,7 @@ import { type ComponentProps } from 'react'
import { CodeBlock } from '../ui/CodeBlock/CodeBlock'
-async function getRefMarkdownInternal(relPath: string) {
+async function readRefMdx(relPath: string) {
const fullPath = join(REF_DOCS_DIRECTORY, relPath + '.mdx')
try {
@@ -20,11 +20,10 @@ async function getRefMarkdownInternal(relPath: string) {
}
const mdx = await readFile(fullPath, 'utf-8')
- const { content } = matter(mdx)
- return content
+ return matter(mdx)
} catch (err) {
console.error(`Error fetching reference markdown from file: ${fullPath}:\n\n${err}`)
- return ''
+ return { content: '', data: {} as Record<string, unknown> }
}
}
@@ -34,7 +33,13 @@ async function getRefMarkdownInternal(relPath: string) {
* here: this is just reading the public MDX files from the codebase.
*/
const getRefMarkdown = cache_fullProcess_withDevCacheBust(
- getRefMarkdownInternal,
+ async (relPath: string) => (await readRefMdx(relPath)).content,
+ REF_DOCS_DIRECTORY,
+ (filename: string) => JSON.stringify([filename.replace(/\.mdx$/, '')])
+)
+
+const getRefFrontmatter = cache_fullProcess_withDevCacheBust(
+ async (relPath: string) => (await readRefMdx(relPath)).data,
REF_DOCS_DIRECTORY,
(filename: string) => JSON.stringify([filename.replace(/\.mdx$/, '')])
)
@@ -60,4 +65,4 @@ function MDXRemoteRefs({ source, codeBlockProps }: MDXRemoteRefsProps) {
return <MDXRemoteBase source={source} components={refComponents} />
}
-export { getRefMarkdown, MDXRemoteRefs }
+export { getRefFrontmatter, getRefMarkdown, MDXRemoteRefs }
diff --git a/apps/docs/features/docs/Reference.sidebar.tsx b/apps/docs/features/docs/Reference.sidebar.tsx
new file mode 100644
index 00000000000..8f7de070e68
--- /dev/null
+++ b/apps/docs/features/docs/Reference.sidebar.tsx
@@ -0,0 +1,66 @@
+'use client'
+
+import { Feedback } from '~/components/Feedback'
+import { useTocAnchors } from '~/features/docs/GuidesMdx.state'
+import { MdxAnchor } from '~/features/docs/MdxAnchor'
+import { isFeatureEnabled } from 'common'
+import { usePathname } from 'next/navigation'
+import { cn } from 'ui'
+import { TocSection } from 'ui-patterns/Toc'
+
+export type ReferenceLink = { title: string; href: string }
+
+export function ReferenceLinks({
+ links,
+ className,
+}: {
+ links: ReferenceLink[]
+ className?: string
+}) {
+ return (
+ <div className={className}>
+ <h3 className="font-mono text-xs uppercase text-foreground">Additional links</h3>
+ <ul className="mt-2 flex flex-col gap-1.5 text-sm">
+ {links.map((link) => (
+ <li key={link.href}>
+ <MdxAnchor href={link.href} className="text-foreground-lighter">
+ {link.title}
+ </MdxAnchor>
+ </li>
+ ))}
+ </ul>
+ </div>
+ )
+}
+
+interface ReferenceSidebarProps {
+ className?: string
+ links?: ReferenceLink[]
+}
+
+/**
+ * Right-hand sidebar for reference pages that render prose (e.g. the
+ * Management API introduction). Mirrors `GuidesSidebar` minus the AI tools,
+ * which need a per-page markdown file that reference pages don't have yet,
+ * plus a list of additional links.
+ */
+export function ReferenceSidebar({ className, links = [] }: ReferenceSidebarProps) {
+ const pathname = usePathname()
+ const { toc } = useTocAnchors()
+ const showFeedback = isFeatureEnabled('feedback:docs')
+
+ 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">
+ {showFeedback && (
+ <div className="pl-5">
+ <Feedback key={pathname} />
+ </div>
+ )}
+ {/* `static`: the default sticky offset pins the list while the links below scroll over it */}
+ {toc.length !== 0 && <TocSection items={toc} className="static" />}
+ {links.length !== 0 && <ReferenceLinks links={links} className="pl-5" />}
+ </div>
+ </div>
+ )
+}
diff --git a/apps/docs/internals/generate-reference-markdown.ts b/apps/docs/internals/generate-reference-markdown.ts
index d985a788e12..d78df3e5337 100644
--- a/apps/docs/internals/generate-reference-markdown.ts
+++ b/apps/docs/internals/generate-reference-markdown.ts
@@ -247,7 +247,15 @@ async function renderMarkdownSection(mdxDir: string, section: Section): Promise<
return null
}
const { content, data } = matter(raw)
- const body = stripMdxJsx(content)
+ const links: Array<{ title: string; href: string }> = Array.isArray(data.links) ? data.links : []
+ const body = [
+ stripMdxJsx(content),
+ links.length
+ ? `## Additional links\n\n${links.map((l) => `- [${l.title}](${l.href})`).join('\n')}`
+ : '',
+ ]
+ .filter(Boolean)
+ .join('\n\n')
if (!body) return null
const heading = data.hideTitle
? null