Merge pull request #556 from easyops-cn/steve/ask-ai

feat: support Ask AI

Author: weareoutman

README.md

@@ -26,9 +26,35 @@ https://easyops-cn.github.io/docusaurus-search-local/
 
 ## Screen Shots
 
-![Screen Shot EN](screen-shots/screen-shot-en.png)
+<p align="center">
+  <img src="screen-shots/screen-shot-en.png" alt="Screen Shot EN" width="591" />
+</p>
 
-![Screen Shot ZH](screen-shots/screen-shot-zh.png)
+<p align="center">
+  <img src="screen-shots/screen-shot-zh.png" alt="Screen Shot ZH" width="602" />
+</p>
+
+## ✨ Ask AI Support
+
+This plugin now supports **Ask AI** integration! Enable AI-powered assistance directly in your documentation site to help users get instant, context-aware answers.
+
+NOTE: Ask AI feature requires an external AI service. Please refer to the [Open Ask AI Server](https://github.com/easyops-cn/open-ask-ai-server), which is a serverless solution, and can be used **for free** using Vercel Hobby Plan!
+
+<p align="center">
+  <img src="screen-shots/ask-ai-01.png" alt="Ask AI Screenshot 1" width="602" />
+</p>
+
+<p align="center">
+  <img src="screen-shots/ask-ai-02.png" alt="Ask AI Screenshot 2" width="631" />
+</p>
+
+With Ask AI enabled, users can:
+
+- Get intelligent answers based on your documentation
+- Access AI assistance with a simple keyboard shortcut
+- Receive context-aware responses tailored to your content
+
+See the [askAi option](#theme-options) in Theme Options below for configuration details.
 
 ## Installation
 
@@ -65,6 +91,13 @@ module.exports = {
 
         // If you're using `noIndex: true`, set `forceIgnoreNoIndex` to enable local index:
         // forceIgnoreNoIndex: true,
+
+        // Enable Ask AI integration:
+        // askAi: {
+        //   project: "your-project-name",
+        //   apiUrl: "https://your-api-url.com/api/stream",
+        //   hotkey: "cmd+I", // Optional: keyboard shortcut to trigger Ask AI
+        // },
       }),
     ],
   ],
@@ -96,7 +129,7 @@ module.exports = {
 | ignoreCssSelectors                | string \| string[]                                                          | `[]`      | A list of css selectors to ignore when indexing each page.                                                                                                                                                                                                                                                                                                  |
 | searchBarShortcut                 | boolean                                                                     | `true`    | Whether to enable keyboard shortcut to focus in search bar.                                                                                                                                                                                                                                                                                                 |
 | searchBarShortcutHint             | boolean                                                                     | `true`    | Whether to show keyboard shortcut hint in search bar. Disable it if you need to hide the hint while shortcut is still enabled.                                                                                                                                                                                                                              |
-| searchBarShortcutKeymap           | string                                                                      | `"mod+k"` | Custom keyboard shortcut to focus the search bar. Supports formats like: `"s"` for single key, `"ctrl+k"` for key combinations, `"mod+k"` for Command+K (Mac) / Ctrl+K (others) - recommended cross-platform option, `"ctrl+shift+k"` for multiple modifiers.                                                                                            |
+| searchBarShortcutKeymap           | string                                                                      | `"mod+k"` | Custom keyboard shortcut to focus the search bar. Supports formats like: `"s"` for single key, `"ctrl+k"` for key combinations, `"mod+k"` for Command+K (Mac) / Ctrl+K (others) - recommended cross-platform option, `"ctrl+shift+k"` for multiple modifiers.                                                                                               |
 | searchBarPosition                 | `"auto"` \| `"left"` \| `"right"`                                           | `"auto"`  | The side of the navbar the search bar should appear on. By default, it will try to autodetect based on your docusaurus config according to [the docs](https://docusaurus.io/docs/api/themes/configuration#navbar-search).                                                                                                                                   |
 | docsPluginIdForPreferredVersion   | string                                                                      |           | When you're using multi-instance of docs, set the docs plugin id which you'd like to check the preferred version with, for the search index.                                                                                                                                                                                                                |
 | zhUserDict                        | string                                                                      |           | Provide your custom dict for language of zh, [see here](https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8)                                                                                                                                                                                                                                |
@@ -106,6 +139,7 @@ module.exports = {
 | useAllContextsWithNoSearchContext | boolean                                                                     | `false`   | Whether to show results from all the contexts if no context is provided. This option should not be used with `hideSearchBarWithNoSearchContext: true` as this would show results when there is no search context. This will duplicate indexes and might have a performance cost depending on the index sizes.                                               |
 | `forceIgnoreNoIndex`              | boolean                                                                     | `false`   | Force enable search index even if `noIndex: true` is set, this also affects unlisted articles.                                                                                                                                                                                                                                                              |
 | `fuzzyMatchingDistance`           | number                                                                      | `1`       | Set the edit distance for fuzzy matching during searches.                                                                                                                                                                                                                                                                                                   |
+| `askAi`                           | object                                                                      |           | Configuration for Ask AI widget integration. When not set, the Ask AI feature will be disabled. Required properties: `project` (string), `apiUrl` (string). Optional: `hotkey` (string, e.g., "cmd+I"). See [Ask AI Support](#-ask-ai-support) for more details.                                                                                            |
 
 ### I18N
 

docusaurus-search-local/package.json

@@ -46,6 +46,7 @@
     "lunr": "^2.3.9",
     "lunr-languages": "^1.4.0",
     "mark.js": "^8.11.1",
+    "open-ask-ai": "^0.7.3",
     "tslib": "^2.4.0"
   },
   "devDependencies": {

docusaurus-search-local/src/client/theme/SearchBar/SearchBar.module.css

@@ -17,10 +17,37 @@
 }
 
 .searchInput:focus {
-  outline: 2px solid var(--search-local-input-active-border-color, var(--ifm-color-primary));
+  outline: 2px solid
+    var(--search-local-input-active-border-color, var(--ifm-color-primary));
   outline-offset: 0px;
 }
 
+html[data-theme="dark"] div:global(.ask-ai),
+div:global(.ask-ai) {
+  --ask-ai-primary: var(--ifm-color-primary);
+  --ask-ai-primary-hover: var(--ifm-color-primary-light);
+  --ask-ai-foreground: var(--ifm-color-content);
+  --ask-ai-border: var(--ifm-color-emphasis-300);
+  --ask-ai-error: var(--ifm-color-danger);
+  --ask-ai-button-bg: var(--ifm-color-emphasis-200);
+}
+
+:global(.ask-ai) {
+  --ask-ai-background: var(--search-local-modal-background, #f5f6f7);
+  --ask-ai-muted: var(--search-local-muted-color, #969faf);
+}
+
+html[data-theme="dark"] :global(.ask-ai) {
+  --ask-ai-background: var(
+    --search-local-modal-background,
+    var(--ifm-background-color)
+  );
+  --ask-ai-muted: var(
+    --search-local-muted-color,
+    var(--ifm-color-secondary-darkest)
+  );
+}
+
 @media not (max-width: 996px) {
   .searchBar.searchBarLeft .dropdownMenu {
     left: 0 !important;

docusaurus-search-local/src/client/theme/SearchBar/SearchBar.tsx

@@ -14,11 +14,13 @@ import {
   useActivePlugin,
   useActiveVersion,
 } from "@docusaurus/plugin-content-docs/client";
+import { AskAIWidget, AskAIWidgetRef } from "open-ask-ai";
+import "open-ask-ai/styles.css";
 
 import { fetchIndexesByWorker, searchByWorker } from "../searchByWorker";
 import { SuggestionTemplate } from "./SuggestionTemplate";
 import { EmptyTemplate } from "./EmptyTemplate";
-import { SearchResult } from "../../../shared/interfaces";
+import { SearchDocumentType, SearchResult } from "../../../shared/interfaces";
 import {
   Mark,
   searchBarShortcut,
@@ -29,6 +31,7 @@ import {
   searchContextByPaths,
   hideSearchBarWithNoSearchContext,
   useAllContextsWithNoSearchContext,
+  askAi,
 } from "../../utils/proxiedGenerated";
 import LoadingRing from "../LoadingRing/LoadingRing";
 import { normalizeContextByPath } from "../../utils/normalizeContextByPath";
@@ -58,6 +61,11 @@ interface SearchBarProps {
   handleSearchBarToggle?: (expanded: boolean) => void;
 }
 
+interface TemplateProps {
+  query: string;
+  isEmpty: boolean;
+}
+
 export default function SearchBar({
   handleSearchBarToggle,
 }: SearchBarProps): ReactElement {
@@ -88,6 +96,7 @@ export default function SearchBar({
   const [inputChanged, setInputChanged] = useState(false);
   const [inputValue, setInputValue] = useState("");
   const search = useRef<any>(null);
+  const askAIWidgetRef = useRef<AskAIWidgetRef>(null);
 
   const prevSearchContext = useRef<string>("");
   const [searchContext, setSearchContext] = useState<string>("");
@@ -146,10 +155,7 @@ export default function SearchBar({
     const searchFooterLinkElement = ({
       query,
       isEmpty,
-    }: {
-      query: string;
-      isEmpty: boolean;
-    }): HTMLAnchorElement => {
+    }: TemplateProps): HTMLAnchorElement => {
       const a = document.createElement("a");
       const params = new URLSearchParams();
 
@@ -255,12 +261,29 @@ export default function SearchBar({
               input,
               searchResultLimits
             );
-            callback(result);
+            if (input && askAi) {
+              callback([
+                {
+                  document: {
+                    i: -1,
+                    t: "",
+                    u: "",
+                  },
+                  type: SearchDocumentType.AskAI,
+                  page: undefined,
+                  metadata: {},
+                  tokens: [input],
+                } as Partial<SearchResult> as SearchResult,
+                ...result,
+              ]);
+            } else {
+              callback(result);
+            }
           },
           templates: {
             suggestion: SuggestionTemplate,
             empty: EmptyTemplate,
-            footer: ({ query, isEmpty }: any) => {
+            footer: ({ query, isEmpty }: TemplateProps) => {
               if (
                 isEmpty &&
                 (!searchContext || !useAllContextsWithNoSearchContext)
@@ -279,9 +302,17 @@ export default function SearchBar({
     )
       .on(
         "autocomplete:selected",
-        function (event: any, { document: { u, h }, tokens }: SearchResult) {
+        function (
+          event: any,
+          { document: { u, h }, type, tokens }: SearchResult
+        ) {
           searchBarRef.current?.blur();
 
+          if (type === SearchDocumentType.AskAI && askAi) {
+            askAIWidgetRef.current?.openWithNewSession(tokens.join(""));
+            return;
+          }
+
           let url = u;
           if (Mark && tokens.length > 0) {
             const params = new URLSearchParams();
@@ -457,6 +488,11 @@ export default function SearchBar({
         ref={searchBarRef}
         value={inputValue}
       />
+      {askAi && (
+        <AskAIWidget ref={askAIWidgetRef} {...askAi}>
+          <span hidden></span>
+        </AskAIWidget>
+      )}
       <LoadingRing className={styles.searchBarLoadingRing} />
       {searchBarShortcut &&
         searchBarShortcutHint &&

docusaurus-search-local/src/client/theme/SearchBar/SuggestionTemplate.ts

@@ -4,12 +4,14 @@ import {
   SearchResult,
 } from "../../../shared/interfaces";
 import { concatDocumentPath } from "../../utils/concatDocumentPath";
+import { escapeHtml } from "../../utils/escapeHtml";
 import { getStemmedPositions } from "../../utils/getStemmedPositions";
 import { highlight } from "../../utils/highlight";
 import { highlightStemmed } from "../../utils/highlightStemmed";
 import { explicitSearchResultPath } from "../../utils/proxiedGenerated";
 import {
   iconAction,
+  iconAskAI,
   iconContent,
   iconHeading,
   iconTitle,
@@ -27,6 +29,17 @@ export function SuggestionTemplate({
   isInterOfTree,
   isLastOfTree,
 }: Omit<SearchResult, "score" | "index">): string {
+  if (type === SearchDocumentType.AskAI) {
+    return [
+      `<span class="${styles.hitIcon}">${iconAskAI}</span>`,
+      `<span class="${styles.hitWrapper}">`,
+      `<span class="${styles.hitTitle}">Ask AI: <mark>${escapeHtml(
+        tokens.join(" ")
+      )}</mark></span>`,
+      `</span>`,
+    ].join("");
+  }
+
   const isTitle = type === SearchDocumentType.Title;
   const isKeywords = type === SearchDocumentType.Keywords;
   const isTitleRelated = isTitle || isKeywords;

docusaurus-search-local/src/client/theme/SearchBar/icons.ts

@@ -12,3 +12,5 @@ export const iconTreeInter =
   '<svg viewBox="0 0 24 54"><g stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"><path d="M8 6v42M20 27H8.3"></path></g></svg>';
 export const iconTreeLast =
   '<svg viewBox="0 0 24 54"><g stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"><path d="M8 6v21M20 27H8.3"></path></g></svg>';
+export const iconAskAI =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-sparkles-icon lucide-sparkles"><path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z"/><path d="M20 2v4"/><path d="M22 4h-4"/><circle cx="4" cy="20" r="2"/></svg>';

docusaurus-search-local/src/declarations.ts

@@ -1,3 +1,8 @@
+declare module "ai" {
+  export interface UIMessage {}
+  export interface UIMessageChunk {}
+}
+
 declare module "@easyops-cn/autocomplete.js" {
   export const noConflict: () => void;
 }
@@ -24,6 +29,7 @@ declare module "*/generated.js" {
   export const hideSearchBarWithNoSearchContext: boolean;
   export const useAllContextsWithNoSearchContext: boolean;
   export const forceIgnoreNoIndex: boolean;
+  export const askAi: import("open-ask-ai").AskAIWidgetProps;
 }
 
 declare module "*/generated-constants.js" {

docusaurus-search-local/src/index.ts

@@ -1,3 +1,5 @@
+import { AskAIWidgetProps } from "open-ask-ai";
+
 export interface PluginOptions {
   /**
    * Whether to index docs.
@@ -221,4 +223,9 @@ export interface PluginOptions {
    * @default 1
    */
   fuzzyMatchingDistance?: number;
+
+  /**
+   * Configuration for Ask AI widget integration. When not set, the Ask AI feature will be disabled.
+   */
+  askAi?: AskAIWidgetProps;
 }