chore: reorganize docs apps (#7228)

* reorganize docs apps

* add README

* fix directory

* add condition for old docs

www/packages/build-scripts/.eslintrc.cjs

@@ -0,0 +1,9 @@
+const path = require("path")
+
+module.exports = {
+  extends: ["docs"],
+  parserOptions: {
+    project: true,
+    tsconfigRootDir: path.join(__dirname, "..", ".."),
+  },
+}

www/packages/build-scripts/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "build-scripts",
+  "version": "0.0.0",
+  "private": true,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/**"
+  ],
+  "scripts": {
+    "build": "yarn clean && tsc",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "remark-rehype-plugins": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.20",
+    "eslint-config-docs": "*",
+    "rimraf": "^5.0.5",
+    "tsconfig": "*",
+    "types": "*",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  }
+}

www/packages/build-scripts/src/generate-sidebar.ts

@@ -0,0 +1,159 @@
+import type { RawSidebarItemType } from "types"
+import findPageHeading from "./utils/find-page-heading.js"
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "fs"
+import path from "path"
+import { sidebarAttachHrefCommonOptions } from "./index.js"
+import { getFrontMatterUtil } from "remark-rehype-plugins"
+import findMetadataTitle from "./utils/find-metadata-title.js"
+
+type ItemsToAdd = RawSidebarItemType & {
+  sidebar_position?: number
+}
+
+async function getSidebarItems(
+  dir: string,
+  nested = false
+): Promise<ItemsToAdd[]> {
+  const isRefDir = dir.startsWith("/references")
+  const basePath = isRefDir ? path.resolve() : path.resolve("app")
+  const fullPath = path.resolve(basePath, dir.replace(/^\//, ""))
+  const items: ItemsToAdd[] = []
+
+  const files = readdirSync(fullPath)
+  let mainPageIndex = -1
+
+  for (const file of files) {
+    const filePath = path.join(fullPath, file)
+    const fileBasename = path.basename(file)
+    if (fileBasename.startsWith("_")) {
+      continue
+    }
+
+    if (fileBasename !== "page.mdx" && statSync(filePath).isDirectory()) {
+      const newItems = await getSidebarItems(
+        filePath.replace(basePath, ""),
+        true
+      )
+      if (nested && newItems.length > 1) {
+        items.push(
+          ...sidebarAttachHrefCommonOptions([
+            {
+              title:
+                fileBasename.charAt(0).toUpperCase() +
+                fileBasename.substring(1),
+              hasTitleStyling: true,
+              children: newItems,
+            },
+          ])
+        )
+      } else {
+        items.push(...sidebarAttachHrefCommonOptions(newItems))
+      }
+      continue
+    }
+
+    const frontmatter = await getFrontMatterUtil(filePath)
+    if (frontmatter.sidebar_autogenerate_exclude) {
+      continue
+    }
+
+    const fileContent = frontmatter.sidebar_label
+      ? ""
+      : readFileSync(filePath, "utf-8")
+
+    const newItem = sidebarAttachHrefCommonOptions([
+      {
+        path:
+          frontmatter.slug ||
+          filePath.replace(basePath, "").replace(`/${fileBasename}`, ""),
+        title:
+          frontmatter.sidebar_label ||
+          findMetadataTitle(fileContent) ||
+          findPageHeading(fileContent) ||
+          "",
+      },
+    ])[0]
+
+    items.push({
+      ...newItem,
+      sidebar_position: frontmatter.sidebar_position,
+    })
+
+    mainPageIndex = items.length - 1
+  }
+
+  if (mainPageIndex !== -1 && items.length > 1) {
+    // push all other items to be children of that page.
+    const mainPageChildren = [
+      ...items.splice(0, mainPageIndex),
+      ...items.splice(1),
+    ]
+    mainPageChildren.sort(sortItems)
+    items[0].children = mainPageChildren
+  } else if (items.length > 1) {
+    items.sort(sortItems)
+  }
+
+  return items
+}
+
+async function checkItem(
+  item: RawSidebarItemType
+): Promise<RawSidebarItemType> {
+  if (item.autogenerate_path) {
+    item.children = (await getSidebarItems(item.autogenerate_path)).map(
+      (child) => {
+        delete child.sidebar_position
+
+        return child
+      }
+    )
+  }
+
+  if (item.children) {
+    item.children = await Promise.all(
+      item.children.map(async (childItem) => await checkItem(childItem))
+    )
+  }
+
+  return item
+}
+
+export async function generateSidebar(sidebar: RawSidebarItemType[]) {
+  const path = await import("path")
+  const { writeFileSync } = await import("fs")
+
+  const normalizedSidebar = await Promise.all(
+    sidebar.map(async (item) => await checkItem(item))
+  )
+
+  const generatedDirPath = path.resolve("generated")
+
+  if (!existsSync(generatedDirPath)) {
+    mkdirSync(generatedDirPath)
+  }
+
+  // write normalized sidebar
+  writeFileSync(
+    path.resolve(generatedDirPath, "sidebar.mjs"),
+    `export const generatedSidebar = ${JSON.stringify(
+      normalizedSidebar,
+      null,
+      2
+    )}`,
+    {
+      flag: "w",
+    }
+  )
+}
+
+function sortItems(itemA: ItemsToAdd, itemB: ItemsToAdd): number {
+  const itemASidebarPosition = itemA.sidebar_position || 0
+  const itemBSidebarPosition = itemB.sidebar_position || 0
+
+  if (itemASidebarPosition > itemBSidebarPosition) {
+    return 1
+  }
+
+  return itemASidebarPosition < itemBSidebarPosition ? -1 : 0
+}

www/packages/build-scripts/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./generate-sidebar.js"
+
+export * from "./utils/find-metadata-title.js"
+export * from "./utils/find-page-heading.js"
+export * from "./utils/sidebar-attach-href-common-options.js"

www/packages/build-scripts/src/utils/find-metadata-title.ts

@@ -0,0 +1,7 @@
+const REGEX = /export const metadata = {[\s\S]*title: `(?<title>.*)`/
+
+export default function findMetadataTitle(content: string): string | undefined {
+  const headingMatch = REGEX.exec(content)
+
+  return headingMatch?.groups?.title
+}

www/packages/build-scripts/src/utils/find-page-heading.ts

@@ -0,0 +1,7 @@
+const HEADING_REGEX = /# (?<title>.*)/
+
+export default function findPageHeading(content: string): string | undefined {
+  const headingMatch = HEADING_REGEX.exec(content)
+
+  return headingMatch?.groups?.title
+}

www/packages/build-scripts/src/utils/sidebar-attach-href-common-options.ts

@@ -0,0 +1,16 @@
+import { RawSidebarItemType } from "types"
+
+const commonOptions: Partial<RawSidebarItemType> = {
+  loaded: true,
+  isPathHref: true,
+}
+
+export function sidebarAttachHrefCommonOptions(
+  sidebar: RawSidebarItemType[]
+): RawSidebarItemType[] {
+  return sidebar.map((item) => ({
+    ...commonOptions,
+    ...item,
+    children: sidebarAttachHrefCommonOptions(item.children || []),
+  }))
+}

www/packages/build-scripts/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": ["tsconfig/base.json"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "./dist/.tsbuildinfo-client",
+    "noEmit": false,
+    "lib": ["es2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+  },
+  "include": ["src"]
+}