fix: improvements to Algolia DocSearch (#357)

What Changes selectors of API references to improve DocSearch results Implements custom navigation for DocSearch in both API ref and docs. (Uses goTo method for in page navigation, Gatsby navigate for navigation within Gatsby site, changes URL's to API reference to make use of methods implemented to provide better metadata etc.) Implements a new way to make all HTML available in API reference without need the crawler to have Javascript enabled which should allow Algolia to crawl our site faster. Why To provide users with a good search experience within our docs and API reference Testing Tested using a local setup of the Algolia crawler
2021-08-27 14:38:35 +02:00
parent 15161bb0e9
commit d89332b91a
8 changed files with 295 additions and 49 deletions
@@ -1,11 +1,102 @@
-import React from "react"
+import React, { useContext } from "react"
 import { DocSearch } from "@docsearch/react"
 import "../../medusa-plugin-themes/docsearch/theme.css"
+import HitComponent from "./hit-component"
+import NavigationContext from "../../context/navigation-context"
+import { convertToKebabCase } from "../../utils/convert-to-kebab-case"
+import { navigate } from "gatsby-link"

 const algoliaApiKey = process.env.ALGOLIA_API_KEY || "temp"

 const Search = () => {
-  return <DocSearch apiKey={algoliaApiKey} indexName="medusa-commerce" />
+  const { goTo, api } = useContext(NavigationContext)
+
+  const getOtherAPI = () => {
+    if (api === "store") return "admin"
+    if (api === "admin") return "store"
+  }
+
+  const replaceUrl = item => {
+    let { url, hierarchy } = item
+    if (url.includes("api/store") || url.includes("/api/admin")) {
+      url = url.replace("#", "/")
+      if (hierarchy.lvl2) {
+        const index = url.lastIndexOf("/")
+        url =
+          url.substring(0, index) +
+          `/${convertToKebabCase(hierarchy.lvl1)}` +
+          url.substring(index)
+      }
+    }
+    return url
+  }
+
+  /** If result is part of currently viewed API then we scroll to the
+   * concept/method, and update the pages metadata.
+   */
+  const goToHierarchy = item => {
+    const { hierarchy } = item
+    if (hierarchy.lvl2) {
+      goTo({
+        section: convertToKebabCase(hierarchy.lvl1),
+        method: convertToKebabCase(hierarchy.lvl2),
+      })
+    } else {
+      goTo({ section: convertToKebabCase(hierarchy.lvl1) })
+    }
+  }
+
+  /** If result is NOT part of currently viewed API, but still a part of
+   * the Gatsby site, then we use Gatsby's navigate function for improved
+   * linking.
+   */
+  const navigateHierarchy = item => {
+    const { hierarchy } = item
+    if (hierarchy.lvl2) {
+      navigate(
+        `/api/${getOtherAPI()}/${convertToKebabCase(
+          hierarchy.lvl1
+        )}/${convertToKebabCase(hierarchy.lvl2)}`
+      )
+    } else {
+      navigate(`/api/${getOtherAPI()}/${convertToKebabCase(hierarchy.lvl1)}`)
+    }
+  }
+
+  return (
+    <DocSearch
+      apiKey={algoliaApiKey}
+      indexName="medusa-commerce"
+      hitComponent={HitComponent}
+      navigator={{
+        navigate({ item }) {
+          if (item.url.includes(`api/${api}`)) {
+            goToHierarchy(item)
+          } else if (item.url.includes(`api/${getOtherAPI()}`)) {
+            navigateHierarchy(item)
+          } else {
+            window.location = item.url
+          }
+        },
+
+        navigateNewTab({ item }) {
+          const url = replaceUrl(item)
+
+          const windowReference = window.open(url, "_blank", "noopener")
+
+          if (windowReference) {
+            windowReference.focus()
+          }
+        },
+
+        navigateNewWindow({ item }) {
+          const url = replaceUrl(item)
+
+          window.open(url, "_blank", "noopener")
+        },
+      }}
+    />
+  )
 }

 export default Search