docs-util: add support for workflows in markdown theme (#8485)

* add template for workflows

* initial changes

* added support for parallel steps

* added support for when

* added merge options

* fix merge options

* fix to tooltip

* clean up

* remove redirects

* fixes

* theme fixes + added merge options

* generate hook examples + fixes

* changed namespaces

* add custom autogenerator

* change type of additional data

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

@@ -1,15 +1,17 @@
 import type { RawSidebarItemType } from "types"
-import findPageHeading from "./utils/find-page-heading.js"
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "fs"
+import { existsSync, mkdirSync, 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"
+import { getSidebarItemLink, sidebarAttachHrefCommonOptions } from "./index.js"
+import getCoreFlowsRefSidebarChildren from "./utils/get-core-flows-ref-sidebar-children.js"
 
-type ItemsToAdd = RawSidebarItemType & {
+export type ItemsToAdd = RawSidebarItemType & {
   sidebar_position?: number
 }
 
+const customGenerators: Record<string, () => Promise<ItemsToAdd[]>> = {
+  "core-flows": getCoreFlowsRefSidebarChildren,
+}
+
 async function getSidebarItems(
   dir: string,
   nested = false
@@ -52,32 +54,17 @@ async function getSidebarItems(
       continue
     }
 
-    const frontmatter = await getFrontMatterUtil(filePath)
-    if (frontmatter.sidebar_autogenerate_exclude) {
+    const newItem = await getSidebarItemLink({
+      filePath,
+      basePath,
+      fileBasename,
+    })
+
+    if (!newItem) {
       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,
-    })
+    items.push(newItem)
 
     mainPageIndex = items.length - 1
   }
@@ -108,9 +95,12 @@ async function checkItem(
         return child
       }
     )
-  }
-
-  if (item.children) {
+  } else if (
+    item.custom_autogenerate &&
+    Object.hasOwn(customGenerators, item.custom_autogenerate)
+  ) {
+    item.children = await customGenerators[item.custom_autogenerate]()
+  } else if (item.children) {
     item.children = await Promise.all(
       item.children.map(async (childItem) => await checkItem(childItem))
     )

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

@@ -2,4 +2,6 @@ export * from "./generate-sidebar.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/utils/get-core-flows-ref-sidebar-children.ts

@@ -0,0 +1,88 @@
+import { getSidebarItemLink, ItemsToAdd } from "build-scripts"
+import { existsSync, readdirSync } from "fs"
+import path from "path"
+
+export default async function getCoreFlowsRefSidebarChildren(): Promise<
+  ItemsToAdd[]
+> {
+  const projPath = path.resolve()
+  const basePath = path.join(projPath, "references", "core_flows")
+
+  const directories = readdirSync(basePath, {
+    withFileTypes: true,
+  })
+
+  const sidebarItems: ItemsToAdd[] = []
+
+  for (const directory of directories) {
+    if (
+      !directory.isDirectory() ||
+      directory.name.startsWith("core_flows.") ||
+      directory.name === "types" ||
+      directory.name === "interfaces"
+    ) {
+      continue
+    }
+
+    const namespaceBasePath = path.join(basePath, directory.name, "functions")
+
+    if (!existsSync(namespaceBasePath)) {
+      continue
+    }
+
+    const childDirs = readdirSync(namespaceBasePath, {
+      withFileTypes: true,
+    })
+
+    const workflowItems: ItemsToAdd[] = []
+    const stepItems: ItemsToAdd[] = []
+
+    for (const childDir of childDirs) {
+      if (!childDir.isDirectory()) {
+        continue
+      }
+
+      const childDirPath = path.join(namespaceBasePath, childDir.name)
+      const childFile = readdirSync(childDirPath)
+
+      const sidebarItem = await getSidebarItemLink({
+        filePath: path.join(childDirPath, childFile[0]),
+        basePath: projPath,
+        fileBasename: childFile[0],
+      })
+
+      if (sidebarItem) {
+        if (childDir.name.endsWith("Workflow")) {
+          workflowItems.push(sidebarItem)
+        } else {
+          stepItems.push(sidebarItem)
+        }
+      }
+    }
+
+    if (workflowItems.length || stepItems.length) {
+      const item: ItemsToAdd = {
+        title: directory.name.replaceAll("_", " "),
+        children: [],
+      }
+
+      if (workflowItems.length) {
+        item.children!.push({
+          title: "Workflows",
+          children: workflowItems,
+        })
+      }
+
+      if (stepItems.length) {
+        item.children!.push({
+          title: "Steps",
+          children: stepItems,
+        })
+      }
+
+      sidebarItems.push(item)
+    }
+  }
+
+  return sidebarItems
+}

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

@@ -0,0 +1,42 @@
+import { getFrontMatterUtil } from "remark-rehype-plugins"
+import { ItemsToAdd, sidebarAttachHrefCommonOptions } from "../index.js"
+import { readFileSync } from "fs"
+import findMetadataTitle from "./find-metadata-title.js"
+import findPageHeading from "./find-page-heading.js"
+
+export async function getSidebarItemLink({
+  filePath,
+  basePath,
+  fileBasename,
+}: {
+  filePath: string
+  basePath: string
+  fileBasename: string
+}): Promise<ItemsToAdd | undefined> {
+  const frontmatter = await getFrontMatterUtil(filePath)
+  if (frontmatter.sidebar_autogenerate_exclude) {
+    return
+  }
+
+  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]
+
+  return {
+    ...newItem,
+    sidebar_position: frontmatter.sidebar_position,
+  }
+}