docusarus-plugin-search-glean

A Docusarus plugin to integrate Glean search into your Docusaurus site.

Description

This plugin utilizes Glean's SDK to enable both Glean search and AI Agent chat into your documentation. It is a drop-in replacement for the default Docusaurus search plugin.

Features

Glean Search

Enables you to integrate Glean's search into your Docusaurus site.

Glean Chat (AI Agent)

Enables you to integrate Glean's AI Agent chat into your Docusaurus site (requires setting up an AI Agent in Glean).

Installation

npm install docusaurus-plugin-search-glean

or

yarn add docusaurus-plugin-search-glean

Search Configuration

The search feature integrates Glean's search functionality into your Docusaurus site. You can configure search independently of the chat feature.

Basic Plugin Setup for Search

Add the plugin to your docusaurus.config.js with search options:

module.exports = {
  // ...
  plugins: [
    [
      require.resolve('docusaurus-plugin-search-glean'),
      {
        searchOptions: {
          // Search configuration options
        },
      },
    ],
  ],
};

Static Search Configuration

If your documentation doesn't change often, use statically configured search options:

module.exports = {
  // ...
  plugins: [
    [
      require.resolve('docusaurus-plugin-search-glean'),
      {
        searchOptions: {
          filters: [
            { key: 'app', value: 'github' },
            { key: 'type', value: 'page' },
            { key: 'repository', value: '<your repository name>' },
          ],
        },
      },
    ],
  ],
};

Any changes to the docusaurus site will be automatically picked up by Glean and the search content will be updated accordingly.

Dynamic Search Configuration with Collections

If your documentation changes often, utilize Glean collections to dynamically configure search. While this approach is more complex, it ensures that the search configuration is always up-to-date with the current state of your documentation.

To achieve this, you will need to create a Glean collection for your documentation:

1. Create a new Glean collection in the Glean UI.
2. Create an automated collections sync using GitHub Actions workflows and the Glean Collections Sync action.

Example configuration:

docusaurus.config.js:

module.exports = {
  // ...
  plugins: [
    [
      require.resolve('docusaurus-plugin-search-glean'),
      {
        searchOptions: {
          filters: [{ key: 'collection', value: '<collection name>' }],
        },
      },
    ],
  ],
};

glean-collections-sync.yml:

name: Sync Collections

on:
  schedule:
    - cron: '0 0 * * *' # Runs every day at midnight UTC
  workflow_dispatch: # Allows for manual triggering

jobs:
  sync_collections:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Sync collections
        uses: scalvert/glean-collections-sync@v1
        with:
          glean-client-api-url: ${{ secrets.GLEAN_CLIENT_API_URL }}
          glean-client-api-token: ${{ secrets.GLEAN_CLIENT_API_TOKEN }}
          glean-user-email: ${{ secrets.GLEAN_USER_EMAIL }}
          collection-sync-configs: '[{"name": "<collection name>", "query": "<collection query>", "filters": "<collection filters>"}]'

Chat Configuration

The chat feature integrates Glean's AI Agent chat into your Docusaurus site. You can configure chat independently of the search feature.

Basic Plugin Setup for Chat

Add the plugin to your docusaurus.config.js with chat options:

module.exports = {
  // ...
  plugins: [
    [
      require.resolve('docusaurus-plugin-search-glean'),
      {
        chatOptions: {
          agentId: 'your-glean-agent-id',
        },
      },
    ],
  ],
};

Note: The agentId property replaces the legacy applicationId property. While applicationId is still supported for backward compatibility, it will be deprecated in the future. We recommend using agentId for new implementations.

Static Chat Configuration

If your documentation doesn't change often, use statically configured chat options:

module.exports = {
  // ...
  plugins: [
    [
      require.resolve('docusaurus-plugin-search-glean'),
      {
        chatOptions: {
          agentId: 'your-glean-agent-id',
        },
      },
    ],
  ],
};

Note: Changes to the site will not automatically update the knowledge sources for the Glean Agent - those changes must be made manually in Glean.

Dynamic Chat Configuration with Collections

For frequently changing documentation, use Glean collections to configure chat. The Agent's Knowledge Sources should be configured to use the collection.

Example configuration:

docusaurus.config.js:

module.exports = {
  // ...
  plugins: [
    [
      require.resolve('docusaurus-plugin-search-glean'),
      {
        chatOptions: {
          agentId: 'your-glean-agent-id', // The Agent's Knowledge Sources should be configured to use the collection
        },
      },
    ],
  ],
};

Follow the same collections sync setup as described in the Dynamic Search Configuration section.

Making the Chat Page Accessible

When the chat feature is enabled, the plugin automatically creates a dedicated chat page (default path: /chat). However, the plugin does not automatically add navigation links. You need to manually add navigation elements to help users discover and access the chat functionality.

Option 1: Add a Navbar Link

Add a link to the chat page in your site's navigation bar by updating the navbar.items array in docusaurus.config.js:

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      items: [
        // ... your existing navbar items
        {
          label: 'Chat',
          to: '/chat', // Use the same path as your chatPagePath option
          position: 'right',
        },
      ],
    },
  },
};

Option 2: Add a Sidebar Link

If you prefer to add the chat link to a sidebar, you can include it in your sidebar configuration:

// sidebars.js
module.exports = {
  tutorialSidebar: [
    // ... your existing sidebar items
    {
      type: 'link',
      label: 'Chat',
      href: '/chat', // Use the same path as your chatPagePath option
    },
  ],
};

Custom Chat Page Path

If you've configured a custom chatPagePath in your plugin options, make sure to use the same path in your navigation links:

// Plugin configuration
([
  require.resolve('docusaurus-plugin-search-glean'),
  {
    chatPagePath: 'ai-assistant', // Custom path
    chatOptions: {
      agentId: 'your-glean-agent-id',
    },
  },
],
  // Navbar link should match
  {
    label: 'AI Assistant',
    to: '/ai-assistant', // Match your custom chatPagePath
    position: 'right',
  });

Using Both Features Together

You can enable both search and chat features simultaneously by providing both searchOptions and chatOptions:

module.exports = {
  // ...
  plugins: [
    [
      require.resolve('docusaurus-plugin-search-glean'),
      {
        searchOptions: {
          filters: [
            { key: 'app', value: 'github' },
            { key: 'type', value: 'page' },
            { key: 'repository', value: '<your repository name>' },
          ],
        },
        chatOptions: {
          agentId: 'your-glean-agent-id',
        },
      },
    ],
  ],
};

Options

| Property | Type | Description | | --------------------- | -------------------------------------- | ------------------------------------------------------------------------- | | searchOptions | Partial<ModalSearchOptions> \| false | Options for search functionality. Pass false to disable. | | chatOptions | Partial<ChatOptions> \| false | Options for chat functionality. Pass false to disable. | | chatPagePath | string | Path to the chat page within the application. | | enableAnonymousAuth | boolean | If true, the plugin will fetch guest authentication tokens automatically. |

For more information on the search and chat options, refer to the Glean documentation.