docs: revise commerce modules overview pages (#10738)

* revise API Key Module overview

* revise auth module

* support ref sidebar items

* remove examples

* revise cart module

* revise currency

* revise customer module

* revise fulfillment module

* revise inventory module

* revise order module

* revise payment

* revise pricing module

* revise product module

* revise promotion module

* revise region module

* revise sales channel module

* revise stock location module

* revise store module

* revise tax module

* revise user module

* lint content + fix snippets

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

@@ -88,23 +88,35 @@ async function getAutogeneratedSidebarItems(
 }
 
 async function getAutogeneratedTagSidebarItems(
-  tags: string
+  tags: string,
+  type: "link" | "ref",
+  existingChildren?: RawSidebarItem[]
 ): Promise<ItemsToAdd[]> {
   const items: ItemsToAdd[] = []
 
   const parsedTags = parseTags(tags)
 
   items.push(
-    ...parsedTags.map(
-      (tagItem) =>
-        ({
-          type: "link",
-          ...tagItem,
-        }) as ItemsToAdd
-    )
+    ...parsedTags
+      .filter((tagItem) => {
+        return existingChildren?.every((existingItem) => {
+          if (existingItem.type !== "link" && existingItem.type !== "ref") {
+            return true
+          }
+
+          return existingItem.path !== tagItem.path
+        })
+      })
+      .map(
+        (tagItem) =>
+          ({
+            type,
+            ...tagItem,
+          }) as ItemsToAdd
+      )
   )
 
-  return sidebarAttachHrefCommonOptions(items)
+  return sidebarAttachHrefCommonOptions([...(existingChildren || []), ...items])
 }
 
 async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
@@ -130,7 +142,9 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
     })
   } else if (item.autogenerate_tags) {
     item.children = await getAutogeneratedTagSidebarItems(
-      item.autogenerate_tags
+      item.autogenerate_tags,
+      item.autogenerate_as_ref ? "ref" : "link",
+      item.children
     )
   } else if (
     item.custom_autogenerate &&
@@ -138,21 +152,29 @@ async function checkItem(item: RawSidebarItem): Promise<RawSidebarItem> {
   ) {
     item.children = await customGenerators[item.custom_autogenerate]()
   } else if (item.children) {
-    item.children = await Promise.all(
-      item.children.map(async (childItem) => await checkItem(childItem))
-    )
+    item.children = await checkItems(item.children)
   }
 
   return item
 }
 
+async function checkItems(items: RawSidebarItem[]): Promise<RawSidebarItem[]> {
+  return (
+    await Promise.all(items.map(async (item) => await checkItem(item)))
+  ).filter((item) => {
+    if (item.type !== "category" && item.type !== "sub-category") {
+      return true
+    }
+
+    return (item.children?.length || 0) > 0
+  })
+}
+
 export async function generateSidebar(sidebar: RawSidebarItem[]) {
   const path = await import("path")
   const { writeFileSync } = await import("fs")
 
-  const normalizedSidebar = await Promise.all(
-    sidebar.map(async (item) => await checkItem(item))
-  )
+  const normalizedSidebar = await checkItems(sidebar)
 
   const generatedDirPath = path.resolve("generated")
 

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

@@ -27,14 +27,11 @@ const getIntersectionTags = (tags: string): Tag => {
     .map((tagName) => getTagItems(tagName))
     .filter((tag) => tag !== undefined) as Tag[]
 
-  if (!tagsToIntersect.length) {
+  if (tagsToIntersect.length < 2) {
+    // if there are less than 2 tags to intersect, return an empty array
     return []
   }
 
-  if (tagsToIntersect.length === 1) {
-    return tagsToIntersect[0]
-  }
-
   return tagsToIntersect[0].filter((tagItem) => {
     return tagsToIntersect
       .slice(1)