docs: support generating sidebar items with tags (#10672)

* docs: support generating sidebar items with tags

* small fix

* fix dependencies

* test

* test fix

* test fix

* test fix

* test fix

* another fix

* revert change

* fix for resources

www/apps/book/.vercelignore

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

www/apps/book/next.config.mjs

@@ -167,6 +167,12 @@ const nextConfig = {
     }
   },
   redirects,
+  experimental: {
+    outputFileTracingExcludes: {
+      "*": ["node_modules/@medusajs/icons"],
+    },
+  },
+  optimizePackageImports: ["@medusajs/icons", "@medusajs/ui"],
 }
 
 export default withMDX(nextConfig)

www/apps/resources/next.config.mjs

@@ -126,16 +126,12 @@ const nextConfig = {
       },
     ]
   },
-  // Redirects shouldn't be necessary anymore since we have remark / rehype
+  experimental: {
-  // plugins that fix links. But leaving this here in case we need it again.
+    outputFileTracingExcludes: {
-  // async redirects() {
+      "*": ["node_modules/@medusajs/icons"],
-  //   // redirect original file paths to the rewrite
+    },
-  //   return slugChanges.map((item) => ({
+  },
-  //     source: item.origSlug,
+  optimizePackageImports: ["@medusajs/icons", "@medusajs/ui"],
-  //     destination: item.newSlug,
-  //     permanent: true,
-  //   }))
-  // },
 }
 
 const withBundleAnalyzer = bundleAnalyzer({

www/apps/resources/scripts/prepare.mjs

@@ -6,11 +6,11 @@ import { sidebar } from "../sidebar.mjs"
 import path from "path"
 
 async function main() {
+  await generateTags(path.resolve("..", "..", "packages", "tags"))
   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 { getFileSlug } from "../../../packages/docs-utils/dist"
+import { getFileSlug } from "docs-utils"
 
 const monoRepoPath = path.resolve("..", "..", "..")
 

www/package.json

@@ -9,7 +9,7 @@
   },
   "scripts": {
     "build": "turbo run build",
-    "build:docs": "turbo run build --filter=docs-v2",
+    "build:docs": "turbo run build --filter=book",
     "build:resources": "turbo run build --filter=resources",
     "build:user-guide": "turbo run build --filter=user-guide",
     "build:packages": "turbo run build --filter='./packages/*'",

www/packages/build-scripts/package.json

@@ -28,16 +28,19 @@
     "watch": "tsc --watch"
   },
   "dependencies": {
-    "remark-rehype-plugins": "*"
+    "docs-utils": "*",
+    "tags": "*"
   },
   "devDependencies": {
     "@types/node": "^20.11.20",
-    "docs-utils": "*",
     "rimraf": "^5.0.5",
     "tsconfig": "*",
     "types": "*",
     "typescript": "^5.3.3"
   },
+  "peerDependencies": {
+    "docs-utils": "*"
+  },
   "engines": {
     "node": ">=18.17.0"
   }

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

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readdirSync, statSync } from "fs"
 import path from "path"
 import { getSidebarItemLink, sidebarAttachHrefCommonOptions } from "./index.js"
 import getCoreFlowsRefSidebarChildren from "./utils/get-core-flows-ref-sidebar-children.js"
+import { parseTags } from "./utils/parse-tags.js"
 
 export type ItemsToAdd = SidebarItem & {
   sidebar_position?: number
@@ -12,7 +13,7 @@ const customGenerators: Record<string, () => Promise<ItemsToAdd[]>> = {
   "core-flows": getCoreFlowsRefSidebarChildren,
 }
 
-async function getSidebarItems(
+async function getAutogeneratedSidebarItems(
   dir: string,
   nested = false
 ): Promise<ItemsToAdd[]> {
@@ -32,7 +33,7 @@ async function getSidebarItems(
     }
 
     if (fileBasename !== "page.mdx" && statSync(filePath).isDirectory()) {
-      const newItems = await getSidebarItems(
+      const newItems = await getAutogeneratedSidebarItems(
         filePath.replace(basePath, ""),
         true
       )
@@ -86,6 +87,26 @@ async function getSidebarItems(
   return items
 }
 
+async function getAutogeneratedTagSidebarItems(
+  tags: string
+): Promise<ItemsToAdd[]> {
+  const items: ItemsToAdd[] = []
+
+  const parsedTags = parseTags(tags)
+
+  items.push(
+    ...parsedTags.map(
+      (tagItem) =>
+        ({
+          type: "link",
+          ...tagItem,
+        }) as ItemsToAdd
+    )
+  )
+
+  return sidebarAttachHrefCommonOptions(items)
+}
+
 async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
   if (!item.type) {
     throw new Error(
@@ -100,12 +121,16 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
     return item
   }
   if (item.autogenerate_path) {
-    item.children = (await getSidebarItems(item.autogenerate_path)).map(
+    item.children = (
-      (child) => {
+      await getAutogeneratedSidebarItems(item.autogenerate_path)
-        delete child.sidebar_position
+    ).map((child) => {
+      delete child.sidebar_position
 
-        return child
+      return child
-      }
+    })
+  } else if (item.autogenerate_tags) {
+    item.children = await getAutogeneratedTagSidebarItems(
+      item.autogenerate_tags
     )
   } else if (
     item.custom_autogenerate &&

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

@@ -1,6 +1,6 @@
 import { readdirSync } from "fs"
 import path from "path"
-import { getFileSlugSync } from "../../docs-utils/dist/index.js"
+import { getFileSlugSync } from "docs-utils"
 
 type Options = {
   basePath: string

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

@@ -1,4 +1,4 @@
-import { getFrontMatter, findPageTitle } from "../../../docs-utils/dist/index.js"
+import { getFrontMatter, findPageTitle } from "docs-utils"
 import { ItemsToAdd, sidebarAttachHrefCommonOptions } from "../index.js"
 import { InteractiveSidebarItem } from "types"
 

www/packages/build-scripts/src/utils/parse-tags.ts

@@ -0,0 +1,44 @@
+import { getTagItems } from "tags"
+import { Tag } from "types"
+
+export const parseTags = (tagNames: string): Tag => {
+  const parsedTags: Tag = []
+  tagNames.split(",").forEach((tagName) => {
+    const intersectingTags = getIntersectionTags(tagName)
+
+    if (!intersectingTags.length) {
+      return
+    }
+
+    parsedTags.push(...intersectingTags)
+  })
+
+  return parsedTags
+}
+
+const getIntersectionTags = (tags: string): Tag => {
+  const tagsToIntersect: Tag[] = tags
+    .split("+")
+    .map((tagName) => getTagItems(tagName))
+    .filter((tag) => tag !== undefined) as Tag[]
+
+  if (!tagsToIntersect.length) {
+    return []
+  }
+
+  if (tagsToIntersect.length === 1) {
+    return tagsToIntersect[0]
+  }
+
+  return tagsToIntersect[0].filter((tagItem) => {
+    return tagsToIntersect
+      .slice(1)
+      .every((otherTag) =>
+        otherTag.some(
+          (otherTagItem) =>
+            otherTagItem.title === tagItem.title &&
+            otherTagItem.path === tagItem.path
+        )
+      )
+  })
+}

www/packages/docs-utils/src/get-file-slug-sync.ts

@@ -0,0 +1,11 @@
+import { matter } from "vfile-matter"
+import { readSync } from "to-vfile"
+import { FrontMatter } from "types"
+
+export function getFileSlugSync(filePath: string): string | undefined {
+  const content = readSync(filePath)
+
+  matter(content)
+
+  return ((content.data.matter as FrontMatter).slug as string) || undefined
+}

www/packages/docs-utils/src/get-file-slug.ts

@@ -1,6 +1,3 @@
-import { matter } from "vfile-matter"
-import { readSync } from "to-vfile"
-import { FrontMatter } from "types"
 import { getFrontMatter } from "./get-front-matter.js"
 
 export async function getFileSlug(
@@ -13,11 +10,3 @@ export async function getFileSlug(
     return fileFrontmatter.slug
   }
 }
-
-export function getFileSlugSync(filePath: string): string | undefined {
-  const content = readSync(filePath)
-
-  matter(content)
-
-  return ((content.data.matter as FrontMatter).slug as string) || undefined
-}

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

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

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

@@ -30,18 +30,12 @@
   "dependencies": {
     "@cloudinary/url-gen": "^1.17.0",
     "docs-utils": "*",
-    "remark-frontmatter": "^5.0.0",
-    "remark-parse": "^11.0.0",
-    "remark-stringify": "^11.0.0",
-    "to-vfile": "^8.0.0",
     "unified": "^11.0.4",
     "unist-builder": "3.0.0",
-    "unist-util-visit": "4.1.2",
+    "unist-util-visit": "4.1.2"
-    "vfile-matter": "^5.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.20",
-    "docs-ui": "*",
     "rimraf": "^5.0.5",
     "tsconfig": "*",
     "types": "*",

www/packages/remark-rehype-plugins/src/utils/fix-link.ts

@@ -1,5 +1,5 @@
 import path from "path"
-import { getFileSlugSync } from "../../../docs-utils/dist/index.js"
+import { getFileSlugSync } from "docs-utils"
 
 export type FixLinkOptions = {
   currentPageFilePath: string

www/packages/types/package.json

@@ -35,12 +35,10 @@
     "@types/node": "^20.11.20",
     "rimraf": "^5.0.5",
     "tsconfig": "*",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "@medusajs/icons": "^2.0.0"
   },
   "engines": {
     "node": ">=18.17.0"
-  },
-  "dependencies": {
-    "@medusajs/icons": "^2.0.0"
   }
 }

www/packages/types/src/sidebar.ts

@@ -57,6 +57,7 @@ export type SidebarSectionItems = {
 
 export type RawSidebarItem = SidebarItem & {
   autogenerate_path?: string
+  autogenerate_tags?: string
   custom_autogenerate?: string
   number?: string
 }

www/yarn.lock

@@ -7215,11 +7215,13 @@ __metadata:
   dependencies:
     "@types/node": ^20.11.20
     docs-utils: "*"
-    remark-rehype-plugins: "*"
     rimraf: ^5.0.5
+    tags: "*"
     tsconfig: "*"
     types: "*"
     typescript: ^5.3.3
+  peerDependencies:
+    docs-utils: "*"
   languageName: unknown
   linkType: soft
 
@@ -14643,20 +14645,14 @@ __metadata:
   dependencies:
     "@cloudinary/url-gen": ^1.17.0
     "@types/node": ^20.11.20
-    docs-ui: "*"
     docs-utils: "*"
-    remark-frontmatter: ^5.0.0
-    remark-parse: ^11.0.0
-    remark-stringify: ^11.0.0
     rimraf: ^5.0.5
-    to-vfile: ^8.0.0
     tsconfig: "*"
     types: "*"
     typescript: ^5.3.3
     unified: ^11.0.4
     unist-builder: 3.0.0
     unist-util-visit: 4.1.2
-    vfile-matter: ^5.0.0
   languageName: unknown
   linkType: soft