Skip to main content

Adding ai12z Search to Your Docusaurus Site

Enhance your Docusaurus documentation site with ai12z's AI-powered search capabilities. This guide will walk you through the steps to integrate ai12z search into your Docusaurus project, whether you're using a JavaScript (docusaurus.config.js) or TypeScript (docusaurus.config.ts) configuration file.

Prerequisites​

  • Docusaurus Project: Ensure you have a Docusaurus site set up. If not, follow the Docusaurus Installation Guide to get started.
  • ai12z Account: Sign up for an ai12z account to obtain your API key.

1. Install Necessary Dependencies​

Make sure you have the required packages installed:

npm install prism-react-renderer @docusaurus/types @docusaurus/preset-classic

2. Update Your Docusaurus Configuration​

Depending on your project setup, you may have a docusaurus.config.js or docusaurus.config.ts file. Follow the instructions relevant to your configuration file type.

For JavaScript Configuration (docusaurus.config.js)​

Modify your docusaurus.config.js file to include the ai12z scripts and stylesheets:

// Import necessary modules
const prismThemes = require("prism-react-renderer").themes

module.exports = {
  // ... existing configurations

  scripts: [
    {
      src: "https://unpkg.com/ai12z@latest/dist/esm/library.js",
      type: "module",
    },
  ],
  stylesheets: ["https://unpkg.com/ai12z@latest/dist/library/library.css"],

  // ... existing configurations

  presets: [
    [
      "classic",
      {
        // ... existing preset configurations
        theme: {
          // ... existing theme configurations
        },
      },
    ],
  ],

  themeConfig: {
    // ... existing theme configurations

    navbar: {
      // ... existing navbar configurations

      items: [
        // ... existing navbar items

        {
          type: "html",
          value:
            '<ai12z-cta data-key="YOUR_AI12Z_API_KEY" heading="" help-text="Type your question and optionally include an image to start your search, then click Ask AI" data-mode="dev"><div slot="cta"><img src="YOUR_ICON_URL" width="20px" height="20px" style="cursor:pointer"></div></ai12z-cta>',
          position: "left",
        },
      ],
    },

    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
}

For TypeScript Configuration (docusaurus.config.ts)​

Modify your docusaurus.config.ts file to include the ai12z scripts and stylesheets:

// Import necessary modules and types
import { themes as prismThemes } from "prism-react-renderer"
import type { Config } from "@docusaurus/types"
import type { Preset } from "@docusaurus/preset-classic"

const config: Config = {
  // ... existing configurations

  scripts: [
    {
      src: "https://unpkg.com/ai12z@latest/dist/esm/library.js",
      type: "module",
    },
  ],
  stylesheets: ["https://unpkg.com/ai12z@latest/dist/library/library.css"],

  // ... existing configurations

  presets: [
    [
      "classic",
      {
        // ... existing preset configurations
        theme: {
          // ... existing theme configurations
        },
      } as Preset.Options,
    ],
  ],

  themeConfig: {
    // ... existing theme configurations

    navbar: {
      // ... existing navbar configurations

      items: [
        // ... existing navbar items

        {
          type: "html",
          value:
            '<ai12z-cta data-key="YOUR_AI12Z_API_KEY" heading="" help-text="Type your question and optionally include an image to start your search, then click Ask AI" data-mode="dev"><div slot="cta"><img src="https://demo.ai12z.com/wp-content/uploads/2024/08/magnifying-glass-solid.svg" width="20px" height="20px" style="cursor:pointer"></div></ai12z-cta>',
          position: "left",
        },
      ],
    },

    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  } as Preset.ThemeConfig,
}

export default config

Notes:

  • Replace YOUR_AI12Z_API_KEY with your actual ai12z API key.
  • Replace YOUR_ICON_URL with the URL of the icon you wish to display in the navbar.

3. Customize the ai12z Component (Optional)​

You can customize the ai12z component to better fit your site's theme and user experience:

<ai12z-cta
  data-key="YOUR_AI12Z_API_KEY"
  heading="Need Assistance?"
  help-text="Ask our AI assistant any question about the documentation."
  data-mode="prod"
>
  <div slot="cta">
    <img
      src="YOUR_ICON_URL"
      width="20px"
      height="20px"
      style="cursor:pointer"
    />
  </div>
</ai12z-cta>
  • data-mode: Set to "prod" for production.
  • heading: Customize the heading displayed in the AI assistant modal.
  • help-text: Provide guidance to users on how to interact with the assistant.

4. Add Custom CSS (Optional)​

If you need to adjust the styling of the ai12z component, you can add custom CSS in src/css/custom.css:

/* Example custom styles for ai12z component */
ai12z-cta {
  /* Your custom styles here */
}

5. Run Your Docusaurus Site​

Start your Docusaurus development server to see the changes:

npm run start

Navigate to http://localhost:3000 to view your site with the integrated ai12z search.

Troubleshooting​

  • Component Not Displaying: Ensure that the script and stylesheet URLs are correct and that your API key is valid.
  • Styling Issues: Verify that your custom CSS does not conflict with the ai12z component styles.
  • TypeScript Errors: If you're using TypeScript and encounter type errors, make sure all imported types are correctly referenced and that your configuration adheres to TypeScript syntax.
  • Console Errors: Check the browser console for any JavaScript errors and address them accordingly.

Additional Resources​

Conclusion​

You've successfully added ai12z's AI-powered search to your Docusaurus site. Whether you're using a JavaScript or TypeScript configuration file, this enhancement will provide your users with a sophisticated search experience, allowing them to find information more efficiently.

Enjoy the enhanced functionality on your documentation site!