IntegrationsMkdocs

Add Chat and Search to MkDocs

Integrate Inkeep's chat button and search bar into your MkDocs documentation for enhanced user experience.

What is MkDocs

MkDocs is a platform for creating documentation with markdown.

Get an API key

Follow these steps to create an API key for your web integration.

Initialize the widget

In docs folder create a custom js file, for example button-and-search-bar.js. Add path to this file to the mkdocs.yml and disable default search bar with plugins: []:

mkdocs.yml
extra_javascript:
  - button-and-search-bar.js
plugins: []

Then add the button and search bar:

button-and-search-bar.js
document.addEventListener("DOMContentLoaded", () => {
  // Load the Inkeep script
  const inkeepScript = document.createElement("script");
  inkeepScript.src =
    "https://cdn.jsdelivr.net/npm/@inkeep/cxkit-js@0.5/dist/embed.js";
  inkeepScript.type = "module";
  inkeepScript.defer = true;
  document.head.appendChild(inkeepScript);
 
  // Create a new div for the Inkeep search bar
  const inkeepDiv = document.createElement("div");
  inkeepDiv.id = "inkeepSearchBar";
 
  // Get the header element where you want to place the Inkeep search bar
  const headerElement = document.querySelector("#navbar-collapse");
  if (headerElement) {
    headerElement.appendChild(inkeepDiv);
  }
 
  const config = {
    baseSettings: {
      apiKey: "INKEEP_API_KEY", // required
      primaryBrandColor: "#26D6FF", // your brand color, widget color scheme is derived from this
      organizationDisplayName: "Inkeep",
      // ...optional settings,
      colorMode: {
        sync: {
          target: document.documentElement,
          attributes: ["data-color-mode-scheme"],
          isDarkMode: (attributes) => {
            const currentTheme = attributes["data-color-mode-scheme"];
            return currentTheme === "dracula" || currentTheme === "dark";
          },
        },
      },
      theme: {
        styles: [
          {
            key: "main",
            type: "link",
            value: "/path/to/stylesheets",
          },
        ],
        // ...optionalSettings,
      },
    },
    modalSettings: {
      // optional settings
    },
    searchSettings: {
      // optional settings
    },
    aiChatSettings: {
      // optional settings
      aiAssistantAvatar: "https://mydomain.com/mylogo", // use your own AI assistant avatar
      exampleQuestions: [
        "Example question 1?",
        "Example question 2?",
        "Example question 3?",
      ],
    },
  };
 
  inkeepScript.addEventListener("load", () => {
    const widgetContainer = document.getElementById("inkeepSearchBar");
 
    Inkeep.ChatButton(config);
    widgetContainer && Inkeep.SearchBar("#inkeepSearchBar", config);
  });
});

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

On this page