Skip to content

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

feat: Add troubleshooting guides index markdown (#47818)

Jeremias Menichellibe35b925ca26
diff --git a/apps/docs/internals/generate-guides-markdown.ts b/apps/docs/internals/generate-guides-markdown.ts
index 5bdca3e1c73..c0c77c12261 100644
--- a/apps/docs/internals/generate-guides-markdown.ts
+++ b/apps/docs/internals/generate-guides-markdown.ts
@@ -12,7 +12,7 @@ import { mdxjs } from 'micromark-extension-mdxjs'
import { parse as parseToml } from 'smol-toml'
import { mcpConfigPanelMarkdown as McpConfigPanel } from 'ui-patterns/McpUrlBuilder/McpConfigPanel.md'
-import { addBaseUrlPrefix } from './internal-links'
+import { addBaseUrlPrefix, getInternalLinkBaseUrl, withDocsBasePath } from './internal-links'
import { AccordionItem } from './markdown-schema/Accordion'
import { Admonition } from './markdown-schema/Admonition'
import { AuthProviders } from './markdown-schema/AuthProviders'
@@ -45,6 +45,13 @@ const PARTIALS_DIR = path.join(process.cwd(), 'content', '_partials')
// markdown. It lives under the gitignored public/markdown/ output dir and is
// regenerated by build:guides-markdown, which turbo runs ahead of build/typecheck/lint.
const MANIFEST_PATH = path.join(process.cwd(), 'public', 'markdown', 'manifest.json')
+const TROUBLESHOOTING_INDEX_PATH = path.join(
+ process.cwd(),
+ 'public',
+ 'markdown',
+ 'guides',
+ 'troubleshooting.md'
+)
type JsxNode = MdxJsxFlowElement | MdxJsxTextElement
type Props = Record<string, unknown>
@@ -207,25 +214,47 @@ async function transformBody(content: string, data: Record<string, unknown>): Pr
return output
}
-async function generateOne(sourceFile: string, frontmatter: FrontmatterFormat): Promise<string> {
+async function parseSingleSource(
+ sourceFile: string,
+ frontmatter: FrontmatterFormat
+): Promise<string> {
const raw = await fs.readFile(sourceFile, 'utf8')
const { content, data } = parseFrontmatter(raw, frontmatter)
return transformBody(content, data)
}
-function renderManifest(sources: MarkdownSource[]): string {
- const slugs = [...new Set(sources.map((source) => source.slug))].sort()
- return `${JSON.stringify(slugs, null, 2)}\n`
+async function renderManifest(sources: MarkdownSource[], extraSlugs: string[] = []): Promise<void> {
+ const slugs = Array.from(new Set([...sources.map((s) => s.slug), ...extraSlugs]))
+ const content = `${JSON.stringify(slugs, null, 2)}\n`
+
+ await fs.mkdir(path.dirname(MANIFEST_PATH), { recursive: true })
+ await fs.writeFile(MANIFEST_PATH, content)
+}
+
+async function renderTroubleshootingIndex(troubleshooting: MarkdownSource[]): Promise<void> {
+ const entries = await Promise.all(
+ troubleshooting.map(async ({ sourceFile, slug }) => {
+ const raw = await fs.readFile(sourceFile, 'utf8')
+ const { data } = parseFrontmatter(raw, 'toml')
+ const url = `${getInternalLinkBaseUrl()}${withDocsBasePath(`/guides/${slug}`)}`
+ return `- [${data.title}](${url})`
+ })
+ )
+ const content = `# Troubleshooting guides\n\n${entries.join('\n')}\n`
+
+ await fs.mkdir(path.dirname(TROUBLESHOOTING_INDEX_PATH), { recursive: true })
+ await fs.writeFile(TROUBLESHOOTING_INDEX_PATH, content)
}
async function generate() {
- const sources = await collectMarkdownSources()
+ const { guides, troubleshooting } = await collectMarkdownSources()
+ const sources = [...guides, ...troubleshooting]
await Promise.all(
sources.map(async ({ sourceFile, outPath, frontmatter }) => {
let output: string
try {
- output = await generateOne(sourceFile, frontmatter)
+ output = await parseSingleSource(sourceFile, frontmatter)
} catch (err) {
throw new Error(
`Failed to process ${sourceFile}: ${err instanceof Error ? err.message : err}`,
@@ -238,11 +267,11 @@ async function generate() {
})
)
- await fs.mkdir(path.dirname(MANIFEST_PATH), { recursive: true })
- await fs.writeFile(MANIFEST_PATH, renderManifest(sources))
+ await renderManifest(sources, ['troubleshooting'])
+ await renderTroubleshootingIndex(troubleshooting)
console.log(
- `Generated ${sources.length} markdown files under public/markdown/guides/ and updated public/markdown/manifest.json`
+ `Generated ${sources.length} markdown files under public/markdown/guides/, troubleshooting guides index at public/markdown/guides/troubleshooting.md and updated public/markdown/manifest.json`
)
}
diff --git a/apps/docs/internals/markdown-sources.ts b/apps/docs/internals/markdown-sources.ts
index 808d29d7210..f44f64c58bc 100644
--- a/apps/docs/internals/markdown-sources.ts
+++ b/apps/docs/internals/markdown-sources.ts
@@ -22,7 +22,12 @@ export function troubleshootingSlug(sourceFile: string): string {
return `troubleshooting/${path.basename(sourceFile, '.mdx')}`
}
-export async function collectMarkdownSources(): Promise<MarkdownSource[]> {
+export interface MarkdownSources {
+ guides: MarkdownSource[]
+ troubleshooting: MarkdownSource[]
+}
+
+export async function collectMarkdownSources(): Promise<MarkdownSources> {
const [guideFiles, troubleshootingFiles] = await Promise.all([
globby([GUIDES_GLOB]),
globby([TROUBLESHOOTING_GLOB]),
@@ -38,5 +43,5 @@ export async function collectMarkdownSources(): Promise<MarkdownSource[]> {
return { sourceFile, slug, outPath: `${OUTPUT_ROOT}/${slug}.md`, frontmatter: 'toml' }
})
- return [...guides, ...troubleshooting]
+ return { guides, troubleshooting }
}