Inkeep light logo
Schedule a callSee it for my content
IntegrationsDocusaurus

Add AI Search & Chat to your Docusaurus docs

What is Docusaurus

Docusaurus is an open-source documentation platform powered by MDX and React.

Get an API key

  1. Go to the Inkeep Dashboard
  2. Select your project under Projects
  3. Go to the Integrations tab
  4. Click on Create integration
  5. Select Web
  6. Provide a Name.
  7. Specify a URL for where this integration will be used.
  8. For production API keys, leave Enforce referrer URL checked.
  9. Click on Create
  10. Click the Example < /> button to get your API key and view suggested settings

For local or staging API keys, see here.

Install the Inkeep plugin

npm install @inkeep/cxkit-docusaurus
bun add @inkeep/cxkit-docusaurus
pnpm add @inkeep/cxkit-docusaurus
yarn add @inkeep/cxkit-docusaurus
Note
Note

If you are already using Algolia DocSearch provided by Docusaurus by default, it will be replaced by our widget.

Сonfiguration settings

You have two configuration options:

  1. Configure the widget in the plugin options.
  2. Configure the widget in standalone config.

Configure the widget in the plugin options

Docusaurus plugins can accept a tuple of [pluginName, options].

In this case, the plugin name is @inkeep/cxkit-docusaurus.

So use like this:

docusaurus.config.js
const inkeepConfig = {
  baseSettings: {
    // see https://docusaurus.io/docs/deployment#using-environment-variables to use docusaurus environment variables
    apiKey: "INKEEP_API_KEY", // required
    primaryBrandColor: "#26D6FF", // required -- your brand color, the widget color scheme is derived from this
    organizationDisplayName: "Inkeep",
    // ...optional settings
    theme: {
      // optional path to a custom stylesheet
      styles: [
        {
          key: "main",
          type: "link",
          value: "/path/to/stylesheets",
        },
      ],
      syntaxHighlighter: {
        lightTheme: lightCodeTheme, // optional -- pass in the Prism theme you're using
        darkTheme: darkCodeTheme, // optional -- pass in the Prism theme you're using
      },
    }
  },
  modalSettings: {
    // optional settings
  },
  searchSettings: {
    // optional settings
  },
  aiChatSettings: {
    // optional settings
    aiAssistantAvatar: "/img/logo.svg", // optional -- use your own ai assistant avatar
    exampleQuestions: [
      "Example question 1?",
      "Example question 2?",
      "Example question 3?",
    ],
  },
}
plugins: [
  ["@inkeep/cxkit-docusaurus", {
    SearchBar: {
      ...inkeepConfig,
    },
    ChatButton: {
      ...inkeepConfig,
    },
  }],
],

Configure the widget in standalone config

In this case, the plugin name is @inkeep/cxkit-docusaurus.

What this means is that you create a config file in your project. By default, you can create an inkeep.config.js or inkeep.config.ts file in the root of your project, and inkeep will automatically pick it up.

inkeep.config.js
window.inkeepConfig = {
  SearchBar: {
    // ...options
  },
  ChatButton: {
    // ...options
  },
};

You can customize the path to the config file in the plugin options:

docusaurus.config.js
plugins: [
  ["@inkeep/cxkit-docusaurus", { config: "./path/to/my-inkeep-config.js" }],
],

We also export a fully typed defineConfig function that you can use to create your config:

inkeep.config.js
const { defineConfig } = require("@inkeep/cxkit-docusaurus");
 
module.exports = defineConfig({
  SearchBar: {
    // ...options
  },
  ChatButton: {
    // ...options
  },
});

For a full list of customizations, check out the Common Settings.

Note
Note

If you have already created a custom SearchBar component (for example via swizzle eject) this will need to be removed in order to use our Search Bar.

FAQ

We support docusaurus versions 2.0.1 and above.

Our plugin swizzles the SearchBar component. If you have a plugin that also swizzles the SearchBar component, you need to ensure that plugin comes after our plugin in your docusaurus.config.js file. This way, your custom SearchBar will override our default one.

To add custom styles to the Inkeep widget in your Docusaurus site, first create a CSS file in your static directory (e.g. static/inkeep-overrides.css). Then specify the URL of the stylesheet in the styles array within the theme object (inside of baseSettings).

For example, if you created a file at static/inkeep-overrides.css, you should set the styles array to:

theme: {
  styles: [
    {
      key: "main",
      type: "link",
      value: "/inkeep-overrides.css",
    },
  ],
},

For additional details on how Docusaurus manages static assets, please refer to the official documentation.

docusaurus.config.js
//..
  SearchBar: {
    // ... rest of your settings
    baseSettings: {
      // ... rest of your baseSettings
      theme: {
        styles: [
          {
            key: "main",
            type: "link",
            value: "/inkeep-overrides.css",
          },
        ],
      },
    },
},

If you need more control or customizations, you can use the React components directly. To do so, follow the react guides: chat button, search bar, embedded chat, custom modal trigger.

A few things to keep in mind:

  • If using Docusaurus 3.4.0 you will need to load the inkeep widget component dynamically and wrap it in a <BrowserOnly> tag. For example:
import React, { useEffect, useState } from "react";
import BrowserOnly from "@docusaurus/BrowserOnly";
 
export default function Widget() {
  const [isOpen, setIsOpen] = useState(false);
  const [ModalSearchAndChat, setModalSearchAndChat] = useState(null);
 
  useEffect(() => {
    (async () => {
      const { InkeepModalSearchAndChat } = await import("@inkeep/cxkit-react");
      setModalSearchAndChat(() => InkeepModalSearchAndChat);
    })();
  }, []);
 
  const inkeepModalSearchAndChatProps = {
    baseSettings: {
      apiKey: "INKEEP_API_KEY", // required
      primaryBrandColor: "#26D6FF", // required -- your brand color, the widget color scheme is derived from this
      organizationDisplayName: "Inkeep",
    },
    modalSettings: {
      isOpen,
      onOpenChange: handleOpenChange,
    },
  };
  };
 
  return (
    <>
      <button
        type="button"
        onClick={() => {
          setIsOpen(true);
        }}
      >
        Ask AI
      </button>
      <BrowserOnly fallback={<div />}>
        {() => {
          return (
            ModalSearchAndChat && <ModalSearchAndChat {...inkeepModalSearchAndChatProps} />
          );
        }}
      </BrowserOnly>
    </>
  );
}
  • If using the ChatButton component, you can create a Footer.js in the themes directory then import the original Footer component and add the Chat Button so that it will be present on each page. For example:
import Footer from "@theme-original/Footer";
import React, { useEffect, useState } from "react";
import BrowserOnly from "@docusaurus/BrowserOnly";
 
export default function FooterWrapper(props) {
  const [ChatButton, setChatButton] = useState(null);
 
  useEffect(() => {
    (async () => {
      const { InkeepChatButton } = await import("@inkeep/cxkit-react");
      setChatButton(() => InkeepChatButton);
    })();
  }, []);
 
  const InkeepChatButtonProps = {
    baseSettings: {
      apiKey: "INKEEP_API_KEY", // required
      primaryBrandColor: "#26D6FF", // required -- your brand color, the widget color scheme is derived from this
      organizationDisplayName: "Inkeep",
    },
  };
 
  return (
    <>
      <BrowserOnly fallback={<div />}>
        {() => {
          return ChatButton && <ChatButton {...InkeepChatButtonProps} />;
        }}
      </BrowserOnly>
      <Footer {...props} />
    </>
  );
}
Add AI Search to your Docusaurus docsAdd AI Chat to your GitBook docs

On this page