docs: add tags package to generate tags (#10666)

* initial changes

* finalize implementation

* run generator on prep

* remove tags package from book

* optimization attempt

* test transpile

* test transpile

* rename utils

* rename directory

* add vercel ignore

* add tags to book

www/.vercelignore

@@ -0,0 +1 @@
+utils

www/apps/book/package.json

@@ -38,6 +38,7 @@
     "eslint-plugin-prettier": "^5.2.1",
     "eslint-plugin-react-hooks": "^5.0.0",
     "postcss": "^8",
+    "tags": "*",
     "tailwind": "*",
     "tailwindcss": "^3.3.0",
     "tsconfig": "*",

www/apps/book/scripts/prepare.mjs

@@ -1,7 +1,10 @@
 import { generateEditedDates } from "build-scripts"
+import path from "path"
+import { generateTags } from "tags"
 
 async function main() {
   await generateEditedDates()
+  await generateTags(path.resolve("..", "..", "packages", "tags"))
 }
 
 void main()

www/apps/resources/.vercelignore

@@ -0,0 +1 @@
+../../utils

www/apps/resources/next.config.mjs

@@ -6,6 +6,7 @@ import {
   typeListLinkFixerPlugin,
   workflowDiagramLinkFixerPlugin,
 } from "remark-rehype-plugins"
+import bundleAnalyzer from "@next/bundle-analyzer"
 import mdxPluginOptions from "./mdx-options.mjs"
 import path from "node:path"
 
@@ -137,4 +138,8 @@ const nextConfig = {
   // },
 }
 
-export default withMDX(nextConfig)
+const withBundleAnalyzer = bundleAnalyzer({
+  enabled: process.env.ANALYZE === "true",
+})
+
+export default withMDX(withBundleAnalyzer(nextConfig))

www/apps/resources/package.json

@@ -27,17 +27,20 @@
     "remark-frontmatter": "^5.0.0"
   },
   "devDependencies": {
+    "@next/bundle-analyzer": "^15.1.1",
     "@types/mdx": "^2.0.13",
     "@types/node": "^20",
     "@types/react": "npm:types-react@rc",
     "@types/react-dom": "npm:types-react@rc",
     "autoprefixer": "^10.0.1",
     "build-scripts": "*",
+    "docs-utils": "*",
     "eslint": "^9.13.0",
     "eslint-plugin-prettier": "^5.2.1",
     "eslint-plugin-react-hooks": "^5.0.0",
     "postcss": "^8",
     "remark-rehype-plugins": "*",
+    "tags": "*",
     "tailwind": "*",
     "tailwindcss": "^3.3.0",
     "ts-node": "^10.9.2",

www/apps/resources/scripts/prepare.mjs

@@ -1,13 +1,16 @@
 import { generateEditedDates, generateSidebar } from "build-scripts"
+import { generateTags } from "tags"
 import { main as generateSlugChanges } from "./generate-slug-changes.mjs"
 import { main as generateFilesMap } from "./generate-files-map.mjs"
 import { sidebar } from "../sidebar.mjs"
+import path from "path"
 
 async function main() {
   await generateSidebar(sidebar)
   await generateSlugChanges()
   await generateFilesMap()
   await generateEditedDates()
+  await generateTags(path.resolve("..", "..", "packages", "tags"))
 }
 
 void main()

www/apps/resources/utils/get-slugs.mjs

@@ -1,6 +1,6 @@
 import { statSync, readdirSync } from "fs"
 import path from "path"
-import { getFileSlugUtil } from "remark-rehype-plugins"
+import { getFileSlug } from "../../../packages/docs-utils/dist"
 
 const monoRepoPath = path.resolve("..", "..", "..")
 
@@ -42,7 +42,7 @@ export default async function getSlugs(options = {}) {
       continue
     }
 
-    const newSlug = await getFileSlugUtil(filePath)
+    const newSlug = await getFileSlug(filePath)
 
     if (newSlug) {
       slugs.push({

www/eslint.config.mjs

@@ -29,6 +29,7 @@ export default [
         "**/public",
         "**/.eslintrc.js",
         "**/generated",
+        "packages/tags/src/tags"
     ],
 }, ...compat.extends(
     "eslint:recommended",

www/package.json

@@ -16,7 +16,8 @@
     "start": "turbo run start:monorepo",
     "dev": "turbo run dev:monorepo",
     "lint": "turbo run lint",
-    "lint:content": "turbo run lint:content"
+    "lint:content": "turbo run lint:content",
+    "watch": "turbo run watch"
   },
   "dependencies": {
     "autoprefixer": "10.4.14",

www/packages/build-scripts/package.json

@@ -24,13 +24,15 @@
   ],
   "scripts": {
     "build": "yarn clean && tsc",
-    "clean": "rimraf dist"
+    "clean": "rimraf dist",
+    "watch": "tsc --watch"
   },
   "dependencies": {
     "remark-rehype-plugins": "*"
   },
   "devDependencies": {
     "@types/node": "^20.11.20",
+    "docs-utils": "*",
     "rimraf": "^5.0.5",
     "tsconfig": "*",
     "types": "*",

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

@@ -2,8 +2,6 @@ export * from "./generate-edited-dates.js"
 export * from "./generate-sidebar.js"
 export * from "./retrieve-mdx-pages.js"
 
-export * from "./utils/find-metadata-title.js"
-export * from "./utils/find-page-heading.js"
 export * from "./utils/get-core-flows-ref-sidebar-children.js"
 export * from "./utils/get-sidebar-item-link.js"
 export * from "./utils/sidebar-attach-href-common-options.js"

www/packages/build-scripts/src/retrieve-mdx-pages.ts

@@ -1,6 +1,6 @@
 import { readdirSync } from "fs"
 import path from "path"
-import { getFileSlugSyncUtil } from "remark-rehype-plugins"
+import { getFileSlugSync } from "../../docs-utils/dist/index.js"
 
 type Options = {
   basePath: string
@@ -24,7 +24,7 @@ export function retrieveMdxPages({ basePath }: Options): string[] {
         continue
       }
 
-      const slug = getFileSlugSyncUtil(filePath)
+      const slug = getFileSlugSync(filePath)
 
       urls.push(
         slug ||

www/packages/build-scripts/src/utils/get-sidebar-item-link.ts

@@ -1,8 +1,5 @@
-import { getFrontMatterUtil } from "remark-rehype-plugins"
+import { getFrontMatter, findPageTitle } from "../../../docs-utils/dist/index.js"
 import { ItemsToAdd, sidebarAttachHrefCommonOptions } from "../index.js"
-import { readFileSync } from "fs"
-import findMetadataTitle from "./find-metadata-title.js"
-import findPageHeading from "./find-page-heading.js"
 import { InteractiveSidebarItem } from "types"
 
 export async function getSidebarItemLink({
@@ -14,26 +11,18 @@ export async function getSidebarItemLink({
   basePath: string
   fileBasename: string
 }): Promise<ItemsToAdd | undefined> {
-  const frontmatter = await getFrontMatterUtil(filePath)
+  const frontmatter = await getFrontMatter(filePath)
   if (frontmatter.sidebar_autogenerate_exclude) {
     return
   }
 
-  const fileContent = frontmatter.sidebar_label
-    ? ""
-    : readFileSync(filePath, "utf-8")
-
   const newItem = sidebarAttachHrefCommonOptions([
     {
       type: "link",
       path:
         frontmatter.slug ||
         filePath.replace(basePath, "").replace(`/${fileBasename}`, ""),
-      title:
-        frontmatter.sidebar_label ||
-        findMetadataTitle(fileContent) ||
-        findPageHeading(fileContent) ||
-        "",
+      title: frontmatter.sidebar_label || findPageTitle(filePath) || "",
     },
   ])[0] as InteractiveSidebarItem
 

www/packages/build-scripts/tsconfig.json

@@ -6,6 +6,7 @@
     "tsBuildInfoFile": "./dist/.tsbuildinfo-client",
     "noEmit": false,
     "lib": ["es2022"],
+    "target": "es2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "declaration": true,

www/packages/docs-utils/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "docs-utils",
+  "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",
+    "watch": "tsc --watch"
+  },
+  "dependencies": {
+    "remark-frontmatter": "^5.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "to-vfile": "^8.0.0",
+    "unified": "^11.0.4",
+    "vfile-matter": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.20",
+    "rimraf": "^5.0.5",
+    "tsconfig": "*",
+    "types": "*",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  }
+}

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

@@ -0,0 +1,23 @@
+import { readFileSync } from "fs"
+
+const REGEX = /export const metadata = {[\s\S]*title: `(?<title>.*)`/
+
+export function findMetadataTitle(content: string): string | undefined {
+  const headingMatch = REGEX.exec(content)
+
+  return headingMatch?.groups?.title
+}
+
+const HEADING_REGEX = /# (?<title>.*)/
+
+export function findPageHeading(content: string): string | undefined {
+  const headingMatch = HEADING_REGEX.exec(content)
+
+  return headingMatch?.groups?.title
+}
+
+export function findPageTitle(filePath: string): string | undefined {
+  const content = readFileSync(filePath, "utf-8")
+
+  return findMetadataTitle(content) || findPageHeading(content)
+}

www/packages/remark-rehype-plugins/src/utils/get-file-slug.ts → www/packages/docs-utils/src/get-file-slug.ts

@@ -1,20 +1,20 @@
-import { getFrontMatterUtil } from "./get-front-matter.js"
 import { matter } from "vfile-matter"
 import { readSync } from "to-vfile"
-import { FrontMatter } from "../types/index.js"
+import { FrontMatter } from "types"
+import { getFrontMatter } from "./get-front-matter.js"
 
-export async function getFileSlugUtil(
+export async function getFileSlug(
   filePath: string
 ): Promise<string | undefined> {
-  const fileFrontmatter = await getFrontMatterUtil(filePath)
+  const fileFrontmatter = await getFrontMatter(filePath)
 
   if (fileFrontmatter.slug) {
     // add to slugs array
     return fileFrontmatter.slug
   }
 }
 
-export function getFileSlugSyncUtil(filePath: string): string | undefined {
+export function getFileSlugSync(filePath: string): string | undefined {
   const content = readSync(filePath)
 
   matter(content)

www/packages/remark-rehype-plugins/src/utils/get-front-matter.ts → www/packages/docs-utils/src/get-front-matter.ts

@@ -2,13 +2,11 @@ import remarkFrontmatter from "remark-frontmatter"
 import remarkParse from "remark-parse"
 import remarkStringify from "remark-stringify"
 import { unified } from "unified"
-import { read } from "to-vfile"
+import { read, readSync } from "to-vfile"
 import { matter } from "vfile-matter"
-import { FrontMatter } from "../types/index.js"
+import { FrontMatter } from "types"
 
-export async function getFrontMatterUtil(
-  filePath: string
-): Promise<FrontMatter> {
+export async function getFrontMatter(filePath: string): Promise<FrontMatter> {
   return (
     await unified()
       .use(remarkParse)
@@ -22,3 +20,11 @@ export async function getFrontMatterUtil(
       .process(await read(filePath))
   ).data.matter as FrontMatter
 }
+
+export function getFrontMatterSync(filePath: string): FrontMatter {
+  const content = readSync(filePath)
+
+  matter(content)
+
+  return content.data.matter as FrontMatter
+}

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

@@ -0,0 +1,3 @@
+export * from "./find-title.js"
+export * from "./get-file-slug.js"
+export * from "./get-front-matter.js"

www/packages/docs-utils/tsconfig.json

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

www/packages/remark-rehype-plugins/package.json

@@ -24,10 +24,12 @@
   ],
   "scripts": {
     "build": "yarn clean && tsc",
-    "clean": "rimraf dist"
+    "clean": "rimraf dist",
+    "watch": "tsc --watch"
   },
   "dependencies": {
     "@cloudinary/url-gen": "^1.17.0",
+    "docs-utils": "*",
     "remark-frontmatter": "^5.0.0",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",

www/packages/remark-rehype-plugins/src/index.ts

@@ -9,5 +9,3 @@ export * from "./type-list-link-fixer.js"
 export * from "./workflow-diagram-link-fixer.js"
 
 export * from "./utils/fix-link.js"
-export * from "./utils/get-file-slug.js"
-export * from "./utils/get-front-matter.js"