docs: add prepare script to generate sidebar (#11894)

www/packages/docs-utils/package.json

@@ -34,6 +34,7 @@
     "remark-mdx": "^3.1.0",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
+    "slugify": "^1.6.6",
     "to-vfile": "^8.0.0",
     "unified": "^11.0.4",
     "vfile-matter": "^5.0.0"

www/packages/docs-utils/src/find-title.ts

@@ -8,14 +8,27 @@ export function findMetadataTitle(content: string): string | undefined {
   return headingMatch?.groups?.title
 }
 
-const HEADING_REGEX = /# (?<title>.*)/
-
 export function findPageHeading(content: string): string | undefined {
-  const headingMatch = HEADING_REGEX.exec(content)
+  const headingMatch = /# (?<title>.*)/.exec(content)
 
   return headingMatch?.groups?.title
 }
 
+export function findAllPageHeadings({
+  content,
+  level = 1,
+}: {
+  content: string
+  level?: number
+}): string[] {
+  const regex = new RegExp(
+    `^${"#".repeat(level)}(?!#) (?<title>.*?)(?:\n|$)`,
+    "gm"
+  )
+  const matches = [...content.matchAll(regex)]
+  return matches.map((match) => match.groups?.title).filter(Boolean) as string[]
+}
+
 export function findPageTitle(filePath: string): string | undefined {
   const content = readFileSync(filePath, "utf-8")
 

www/packages/docs-utils/src/get-clean-md.ts

@@ -1,7 +1,6 @@
 import remarkMdx from "remark-mdx"
 import remarkParse from "remark-parse"
 import remarkStringify from "remark-stringify"
-import { read } from "to-vfile"
 import { FrontMatter, UnistNode, UnistNodeWithData, UnistTree } from "types"
 import { Plugin, Transformer, unified } from "unified"
 import { SKIP } from "unist-util-visit"
@@ -172,6 +171,7 @@ export const getCleanMd = async ({
   parserOptions,
   type = "file",
 }: GetCleanMdOptions): Promise<string> => {
+  const { read } = await import("to-vfile")
   if (type === "file" && !file.endsWith(".md") && !file.endsWith(".mdx")) {
     return ""
   }

www/packages/docs-utils/src/index.ts

@@ -6,3 +6,4 @@ export * from "./get-file-slug-sync.js"
 export * from "./get-file-slug.js"
 export * from "./get-front-matter.js"
 export * from "./oas-file-to-path.js"
+export * from "./sidebar-utils.js"

www/packages/docs-utils/src/sidebar-utils.ts

@@ -0,0 +1,7 @@
+import pkg from "slugify"
+const { default: slugify } = pkg
+
+export function getSectionId(path: string[]) {
+  path = path.map((p) => slugify(p.trim().toLowerCase()))
+  return path.join("_")
+}