docs: fix appending index.html.md to api reference links (#11327)

* docs: fix appending index.html.md to api reference links

* make hash in api reference lower case

www/apps/book/scripts/prepare.mjs

@@ -8,6 +8,7 @@ import {
 } from "build-scripts"
 import {
   addUrlToRelativeLink,
+  changeLinksToHtmlMdPlugin,
   crossProjectLinksPlugin,
   localLinksRehypePlugin,
 } from "remark-rehype-plugins"
@@ -19,34 +20,38 @@ async function main() {
   })
   const baseUrl =
     process.env.NEXT_PUBLIC_PROD_BASE_URL || process.env.NEXT_PUBLIC_BASE_URL
+  const plugins = {
+    before: [
+      [
+        crossProjectLinksPlugin,
+        {
+          baseUrl,
+          projectUrls: {
+            resources: {
+              url: baseUrl,
+            },
+            "user-guide": {
+              url: baseUrl,
+            },
+            ui: {
+              url: baseUrl,
+            },
+            api: {
+              url: baseUrl,
+            },
+          },
+          useBaseUrl: true,
+        },
+      ],
+      [localLinksRehypePlugin],
+    ],
+    after: [[addUrlToRelativeLink, { url: baseUrl }]],
+  }
   await generateLlmsFull({
     outputPath: path.join(process.cwd(), "public", "llms-full.txt"),
     plugins: {
-      before: [
-        [
-          crossProjectLinksPlugin,
-          {
-            baseUrl,
-            projectUrls: {
-              resources: {
-                url: baseUrl,
-              },
-              "user-guide": {
-                url: baseUrl,
-              },
-              ui: {
-                url: baseUrl,
-              },
-              api: {
-                url: baseUrl,
-              },
-            },
-            useBaseUrl: true,
-          },
-        ],
-        [localLinksRehypePlugin],
-      ],
-      after: [[addUrlToRelativeLink, { url: baseUrl }]],
+      ...plugins,
+      after: [...plugins.after, [changeLinksToHtmlMdPlugin]],
     },
     scanDirs: [
       {
@@ -208,6 +213,9 @@ async function main() {
             type: "Admin",
           },
         },
+        options: {
+          plugins,
+        },
       },
       {
         dir: path.join(
@@ -226,6 +234,9 @@ async function main() {
             type: "Store",
           },
         },
+        options: {
+          plugins,
+        },
       },
     ],
   })

www/packages/build-scripts/src/utils/custom-llms-generators.ts

@@ -81,7 +81,8 @@ export const apiRefLlmsGenerator: CustomLlmsGenerator<
 
     Object.entries(fileYaml).forEach(
       ([httpMethod, operation]: [string, any]) => {
-        const hash = `${slugify(operation.tags[0])}_${slugify(operation.operationId)}`
+        const hash =
+          `${slugify(operation.tags[0])}_${slugify(operation.operationId)}`.toLowerCase()
 
         content += `- [${httpMethod.toUpperCase()} ${oasPath}](${options?.baseUrl}#${hash})\n`
       }

www/packages/docs-utils/src/get-clean-md.ts

@@ -145,22 +145,6 @@ const removeFrontmatterPlugin = (): Transformer => {
   }
 }
 
-const changeLinksPlugin = (): Transformer => {
-  return async (tree) => {
-    const { visit } = await import("unist-util-visit")
-
-    visit(tree as UnistTree, ["link"], (node: UnistNode) => {
-      if (
-        node.type === "link" &&
-        node.url?.startsWith("https://docs.medusajs.com") &&
-        !node.url.endsWith("index.html.md")
-      ) {
-        node.url += `/index.html.md`
-      }
-    })
-  }
-}
-
 const getParsedAsString = (file: VFile): string => {
   let content = file.toString().replaceAll(/^([\s]*)\* /gm, "$1- ")
   const frontmatter = file.data.matter as FrontMatter | undefined
@@ -214,8 +198,6 @@ export const getCleanMd = async ({
     unifier.use(...(Array.isArray(plugin) ? plugin : [plugin]))
   })
 
-  unifier.use(changeLinksPlugin)
-
   const content = type === "file" ? await read(file) : file
   const parsed = await unifier.process(content)
 

www/packages/remark-rehype-plugins/src/change-links-md.ts

@@ -0,0 +1,18 @@
+import { UnistNode, UnistTree } from "types"
+import { Transformer } from "unified"
+
+export const changeLinksToHtmlMdPlugin = (): Transformer => {
+  return async (tree) => {
+    const { visit } = await import("unist-util-visit")
+
+    visit(tree as UnistTree, ["link"], (node: UnistNode) => {
+      if (
+        node.type === "link" &&
+        node.url?.startsWith("https://docs.medusajs.com") &&
+        !node.url.endsWith("index.html.md")
+      ) {
+        node.url += `/index.html.md`
+      }
+    })
+  }
+}

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

@@ -1,5 +1,6 @@
 export * from "./add-url-to-relative-link.js"
 export * from "./broken-link-checker.js"
+export * from "./change-links-md.js"
 export * from "./cloudinary-img.js"
 export * from "./cross-project-links.js"
 export * from "./local-links.js"