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/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(
-      (child) => {
-        delete child.sidebar_position
+    item.children = (
+      await getAutogeneratedSidebarItems(item.autogenerate_path)
+    ).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",
-    "vfile-matter": "^5.0.0"
+    "unist-util-visit": "4.1.2"
   },
   "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
 }