Improve search for API terms (#1161)

Searches like "display.scroll" will now return the relevant API section in the results.
It might be nice if these were highlighted but there's not even contiguous text to highlight.

Author: microbit-robert

src/documentation/search/extracts.test.ts

@@ -127,6 +127,14 @@ describe("contextExtracts", () => {
       // Previous bug was an empty match here.
     ]);
   });
+  it("returns the first sentence without matches if no positions are provided", () => {
+    expect(contextExtracts([], "First sentence. Second sentence.")).toEqual([
+      {
+        type: "text",
+        extract: "First sentence.",
+      },
+    ]);
+  });
 });
 
 describe("sortByStart", () => {

src/documentation/search/extracts.ts

@@ -64,7 +64,14 @@ export const contextExtracts = (
   text: string
 ): Extract[] => {
   if (positions.length === 0) {
-    return [];
+    // Fallback if only text in the title (or id for Reference section) is matched.
+    const end = forward(text, 1);
+    return [
+      {
+        type: "text",
+        extract: text.slice(0, end + 1),
+      },
+    ];
   }
   // Find the text around the first match.
   // Highlight all positions within it.

src/documentation/search/search.worker.ts

@@ -129,7 +129,6 @@ const getExtracts = (
 
   return {
     title: fullStringExtracts(allTitlePositions, content.title),
-    // TODO: consider a fallback if only text in the title is matched.
     content: contextExtracts(allContentPositions, content.content),
   };
 };
@@ -234,6 +233,16 @@ export const buildSearchIndex = (
   let customTokenizer: TokenizerFunction | undefined;
   const index = lunr(function () {
     this.ref("id");
+    this.field("id", {
+      boost: 10,
+      extractor: (doc: object) => {
+        // Ensure we match a search query like 'microbit.display.scroll' or 'display.scroll'
+        // to the correct API section.
+        return `${(doc as SearchableContent).id} ${(
+          doc as SearchableContent
+        ).id.replaceAll("microbit.", "")}`;
+      },
+    });
     this.field("title", { boost: 10 });
     this.field("content");
     this.use(languagePlugin);