docs: show possible similar pages on 404 page (#13840)

* docs: show possible similar pages on 404 page

* fix 404 page in api reference

www/apps/api-reference/app/not-found.tsx

@@ -0,0 +1,58 @@
+import { AcademicCapSolid, BookOpen } from "@medusajs/icons"
+import clsx from "clsx"
+import { CardList, H1, H2, MDXComponents, SimilarPages } from "docs-ui"
+import { config } from "../config"
+
+const P = MDXComponents.p as React.FC<
+  React.HTMLAttributes<HTMLParagraphElement>
+>
+const A = MDXComponents.a as React.FC<
+  React.AnchorHTMLAttributes<HTMLAnchorElement>
+>
+
+const NotFoundPage = () => {
+  return (
+    <div
+      className={clsx(
+        "w-full h-fit",
+        "max-w-inner-content-xs sm:max-w-inner-content-sm md:max-w-inner-content-md",
+        "lg:max-w-inner-content-lg xl:max-w-inner-content-xl xxl:max-w-inner-content-xxl",
+        "xxxl:max-w-inner-content-xxxl",
+        "px-docs_1 md:px-docs_4"
+      )}
+    >
+      <H1>Page Not Found</H1>
+      <P>The page you were looking for isn&apos;t available.</P>
+      <P>
+        If you&apos;re looking for Medusa v1 documentation, it&apos;s been moved
+        to <A href="https://docs.medusajs.com/v1">docs.medusajs.com/v1</A>.
+      </P>
+      <P>
+        If you think this is a mistake, please{" "}
+        <A href="https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml">
+          report this issue on GitHub
+        </A>
+        .
+      </P>
+      <SimilarPages />
+      <H2>Other Resources</H2>
+      <CardList
+        itemsPerRow={2}
+        items={[
+          {
+            title: "Get Started Docs",
+            href: `${config.baseUrl}/learn`,
+            icon: BookOpen,
+          },
+          {
+            title: "Commerce Modules",
+            href: `${config.baseUrl}/resources/commerce-modules`,
+            icon: AcademicCapSolid,
+          },
+        ]}
+      />
+    </div>
+  )
+}
+
+export default NotFoundPage

www/apps/book/app/_not-found.mdx

@@ -2,7 +2,7 @@
 hide_content_menu: true
 ---
 
-import { CardList, H1 } from "docs-ui"
+import { CardList, H1, SimilarPages } from "docs-ui"
 import {
   BookOpen,
   AcademicCapSolid,
@@ -22,6 +22,10 @@ If you're looking for Medusa v1 documentation, it's been moved to [docs.medusajs
 
 If you think this is a mistake, please [report this issue on GitHub](https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml).
 
+<SimilarPages />
+
+## Other Resources
+
 <CardList
   itemsPerRow={2}
   items={[

www/apps/cloud/app/not-found.mdx

@@ -2,7 +2,7 @@
 hide_content_menu: true
 ---
 
-import { CardList, H1 } from "docs-ui"
+import { CardList, H1, SimilarPages } from "docs-ui"
 import {
   BookOpen,
   AcademicCapSolid,
@@ -18,14 +18,20 @@ export const metadata = {
 
 The page you were looking for isn't available.
 
+If you're looking for Medusa v1 documentation, it's been moved to [docs.medusajs.com/v1](https://docs.medusajs.com/v1).
+
 If you think this is a mistake, please [report this issue on GitHub](https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml).
 
+<SimilarPages />
+
+## Other Resources
+
 <CardList
   itemsPerRow={2}
   items={[
     {
       title: "Get Started Docs",
-      href: "/",
+      href: "!docs!/learn",
       icon: BookOpen
     },
     {

www/apps/resources/app/not-found.mdx

@@ -2,7 +2,7 @@
 hide_content_menu: true
 ---
 
-import { CardList, H1 } from "docs-ui"
+import { CardList, H1, SimilarPages } from "docs-ui"
 import {
   BookOpen,
   AcademicCapSolid,
@@ -18,8 +18,14 @@ export const metadata = {
 
 The page you were looking for isn't available.
 
+If you're looking for Medusa v1 documentation, it's been moved to [docs.medusajs.com/v1](https://docs.medusajs.com/v1).
+
 If you think this is a mistake, please [report this issue on GitHub](https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml).
 
+<SimilarPages />
+
+## Other Resources
+
 <CardList
   itemsPerRow={2}
   items={[

www/apps/ui/app/not-found.mdx

@@ -2,7 +2,7 @@
 hide_content_menu: true
 ---
 
-import { CardList, H1 } from "docs-ui"
+import { CardList, H1, SimilarPages } from "docs-ui"
 import {
   BookOpen,
   AcademicCapSolid,
@@ -18,14 +18,20 @@ export const metadata = {
 
 The page you were looking for isn't available.
 
+If you're looking for Medusa v1 documentation, it's been moved to [docs.medusajs.com/v1](https://docs.medusajs.com/v1).
+
 If you think this is a mistake, please [report this issue on GitHub](https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml).
 
+<SimilarPages />
+
+## Other Resources
+
 <CardList
   itemsPerRow={2}
   items={[
     {
       title: "Get Started Docs",
-      href: "/",
+      href: "!docs!/learn",
       icon: BookOpen
     },
     {

www/apps/user-guide/app/not-found.mdx

@@ -2,7 +2,7 @@
 hide_content_menu: true
 ---
 
-import { CardList, H1 } from "docs-ui"
+import { CardList, H1, SimilarPages } from "docs-ui"
 import {
   BookOpen,
   AcademicCapSolid,
@@ -18,14 +18,20 @@ export const metadata = {
 
 The page you were looking for isn't available.
 
+If you're looking for Medusa v1 documentation, it's been moved to [docs.medusajs.com/v1](https://docs.medusajs.com/v1).
+
 If you think this is a mistake, please [report this issue on GitHub](https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml).
 
+<SimilarPages />
+
+## Other Resources
+
 <CardList
   itemsPerRow={2}
   items={[
     {
       title: "Get Started Docs",
-      href: "/",
+      href: "!docs!/learn",
       icon: BookOpen
     },
     {

www/packages/docs-ui/src/components/SimilarPages/index.tsx

@@ -0,0 +1,37 @@
+"use client"
+
+import React from "react"
+import { useSimilarPages } from "../../hooks"
+import { H2 } from "../Heading"
+import { MDXComponents } from "../MDXComponents"
+
+const P = MDXComponents.p as React.FC<
+  React.HTMLAttributes<HTMLParagraphElement>
+>
+const Ul = MDXComponents.ul as React.FC<React.HTMLAttributes<HTMLUListElement>>
+const Li = MDXComponents.li as React.FC<React.HTMLAttributes<HTMLLIElement>>
+const A = MDXComponents.a as React.FC<
+  React.AnchorHTMLAttributes<HTMLAnchorElement>
+>
+
+export const SimilarPages = () => {
+  const similarPages = useSimilarPages()
+
+  if (!similarPages.length) {
+    return null
+  }
+
+  return (
+    <div>
+      <H2>Similar Pages</H2>
+      <P>Maybe you&apos;re looking for:</P>
+      <Ul>
+        {similarPages.map((page) => (
+          <Li key={page.id}>
+            <A href={page.url}>{page.title}</A>
+          </Li>
+        ))}
+      </Ul>
+    </div>
+  )
+}

www/packages/docs-ui/src/components/index.ts

@@ -76,6 +76,7 @@ export * from "./Search/Suggestions/Item"
 export * from "./Select"
 export * from "./Sidebar"
 export * from "./Sidebar/Item"
+export * from "./SimilarPages"
 export * from "./SourceCodeLink"
 export * from "./SplitLists"
 export * from "./Table"

www/packages/docs-ui/src/hooks/index.ts

@@ -16,4 +16,5 @@ export * from "./use-request-runner"
 export * from "./use-scroll-utils"
 export * from "./use-search-navigation"
 export * from "./use-select"
+export * from "./use-similar-pages"
 export * from "./use-tabs"

www/packages/docs-ui/src/hooks/use-similar-pages/index.tsx

@@ -0,0 +1,46 @@
+"use client"
+
+import { usePathname } from "next/navigation"
+import { useSearch } from "../../providers"
+import { useEffect, useState } from "react"
+import { HitType } from "../../components"
+
+type SimilarPage = {
+  id: string
+  title: string
+  url: string
+}
+
+export const useSimilarPages = () => {
+  const pathname = usePathname()
+  const { searchClient, selectedIndex } = useSearch()
+  const [similarPages, setSimilarPages] = useState<SimilarPage[]>([])
+
+  useEffect(() => {
+    void searchClient
+      .search<HitType>({
+        requests: [
+          {
+            query: pathname.split("/").join(" ").trim(),
+            indexName: selectedIndex,
+            hitsPerPage: 3,
+            distinct: true,
+          },
+        ],
+      })
+      .then(({ results }) => {
+        const hits = "hits" in results[0] ? results[0].hits : []
+        const pages = hits.map((hit) => ({
+          id: hit.objectID,
+          title: hit.hierarchy.lvl1 || hit.hierarchy.lvl0 || "Untitled",
+          url: hit.url,
+        }))
+        setSimilarPages(pages)
+      })
+      .catch(() => {
+        setSimilarPages([])
+      })
+  }, [pathname, searchClient])
+
+  return similarPages
+}

www/packages/docs-ui/src/providers/Search/index.tsx

@@ -80,12 +80,10 @@ export const SearchProvider = ({
 
   const modalRef = useRef<HTMLDialogElement | null>(null)
 
-  const searchClient: SearchClient = useMemo(() => {
+  const searchClient: SearchClient = useMemo(
-    const algoliaClient = algoliasearch(algolia.appId, algolia.apiKey)
+    () => algoliasearch(algolia.appId, algolia.apiKey),
-    return {
+    [algolia.appId, algolia.apiKey]
-      ...algoliaClient,
+  )
-    }
-  }, [algolia.appId, algolia.apiKey])
 
   useEffect(() => {
     if (initialDefaultIndex !== selectedIndex) {