Skip to content

docsearch.mdx

Latest commit

 

History

History
418 lines (317 loc) · 10.3 KB

docsearch.mdx

File metadata and controls

418 lines (317 loc) · 10.3 KB
Raw
title Getting Started with v4

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Introduction

DocSearch v4 provides a significant upgrade over previous versions, offering enhanced accessibility, responsiveness, and an improved search experience for your documentation. Built on Algolia Autocomplete, DocSearch v4 ensures a seamless integration trusted by leading documentation sites worldwide.

Installation

Looking for the Composable API documentation? You can find it here.

DocSearch packages are available on the npm registry.

Docusaurus users

If your docs site is powered by Docusaurus, use @docsearch/docusaurus-adapter for the latest DocSearch features (including new Ask AI capabilities such as sidepanel support), while keeping @docusaurus/preset-classic.

<Tabs groupId="language" defaultValue="js" values={[ { label: 'JavaScript', value: 'js', }, { label: 'React', value: 'react', } ] }> 

yarn add @docsearch/js@4
# or with npm
npm install @docsearch/js@4

Without package manager

Include CSS in your website's <head>

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />

And the JavaScript at the end of your <body>:

<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>
yarn add @docsearch/react@4
# or
npm install @docsearch/react@4

Without package manager

Include CSS in your website's <head>:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />

And the JavaScript at the end of your <body>:

<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@4"></script>

Optimize first query performance

Enhance your users' first search experience by using preconnect, see Performance optimization below

Implementation

<Tabs groupId="language" defaultValue="js" values={[ { label: 'JavaScript', value: 'js', }, { label: 'React', value: 'react', } ] }>

DocSearch requires a dedicated container in your HTML

<div id="docsearch"></div>

Initialize DocSearch by passing your container:

import docsearch from '@docsearch/js';

import '@docsearch/css';

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
});

DocSearch generates an accessible, fully-functional search input for you automatically.

Integrating DocSearch into your React app is straightforward:

import { DocSearch } from '@docsearch/react';

import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      indexName="YOUR_INDEX_NAME"
      apiKey="YOUR_SEARCH_API_KEY"
    />
  );
}

export default App;

DocSearch generates a fully accessible search input out-of-the-box.

Quick Testing (without credentials)

If you'd like to test DocSearch immediately without your own credentials, use our demo configuration:

<Tabs groupId="language" defaultValue="js" values={[ { label: 'JavaScript', value: 'js', }, { label: 'React', value: 'react', } ] }> 

docsearch({
  appId: 'PMZUYBQDAK',
  apiKey: '24b09689d5b4223813d9b8e48563c8f6',
  indexName: 'docsearch',
  askAi: 'askAIDemo',
});
<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="docsearch"
  askAi="askAIDemo"
/>

Or use our new dedicated DocSearch Playground

Using DocSearch with Ask AI

DocSearch v4 introduces support for Ask AI, Algolia's advanced, AI-powered search capability. Ask AI enhances the user experience by providing contextually relevant and intelligent responses directly from your documentation. You can also use the same askAi configuration object to route chat through Agent Studio.

To enable Ask AI, you can add your Algolia Assistant ID as a string, or use an object for more advanced configuration (such as specifying a different index, credentials, search parameters, or enabling Agent Studio):

<Tabs groupId="askai-format" defaultValue="string" values={[{ label: 'String', value: 'string' }, { label: 'Object', value: 'object' }]}> 

docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
});
docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: {
    indexName: 'YOUR_MARKDOWN_INDEX', // Optional: use a different index for Ask AI
    apiKey: 'YOUR_SEARCH_API_KEY',     // Optional: use a different API key for Ask AI
    appId: 'YOUR_APP_ID',              // Optional: use a different App ID for Ask AI
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'], // Optional: filter Ask AI context
    },
    suggestedQuestions: true // Optional: enable loading suggested questions on the Ask AI new conversation screen
  },
});
  • Use the string form for a simple setup.
  • Use the object form to customize which index, credentials, or filters Ask AI uses.
  • The suggested questions feature is controlled on the Dashboard in the Ask AI section.

Using Agent Studio with DocSearch

To use Algolia Agent Studio as the chat backend, set agentStudio: true inside the askAi object and pass your Agent Studio agent ID as assistantId. Full migration steps (v4, v5, and custom Ask AI API) are in Migrate Ask AI to Agent Studio.

docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    agentStudio: true,
    searchParameters: {
      YOUR_INDEX_NAME: {
        filters: 'type:content AND language:en',
        attributesToRetrieve: ['title', 'content', 'url'],
        restrictSearchableAttributes: ['title', 'content'],
        distinct: 'url',
      },
    },
  },
});
  • agentStudio is configured inside askAi, not as a top-level DocSearch prop.
  • When agentStudio: true, searchParameters must be keyed by index name.
  • Agent Studio search parameters support filters, attributesToRetrieve, restrictSearchableAttributes, and distinct.

Filtering search results

Keyword search

If your website uses DocSearch meta tags or if you've added custom variables to your config, you'll be able to use the facetFilters option to scope your search results to a facet

This is useful to limit the scope of the search to one language or one version.

<Tabs groupId="language" defaultValue="js" values={[ { label: 'JavaScript', value: 'js', }, { label: 'React', value: 'react', } ] }> 

docsearch({
  searchParameters: {
    facetFilters: ['language:en', 'version:1.0.0'],
  },
});
<DocSearch
  searchParameters={{
    facetFilters: ['language:en', 'version:1.0.0'],
  }}
/>

Ask AI

Filtering also applies when using Ask AI. This is useful to limit the scope of the LLM's search to only relevant results.

:::info We recommend using the facetFilters option when using Ask AI with multiple languages or any multi-faceted index. :::

<Tabs groupId="language" defaultValue="js" values={[ { label: 'JavaScript', value: 'js', }, { label: 'React', value: 'react', } ] }> 

docsearch({
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'],
    },
  },
});
```jsx ```

:::tip You can use facetFilters: ['type:content'] to ensure Ask AI only uses records where the type attribute is content (i.e., only records that actually have content). This is useful if your index contains records for navigation, metadata, or other non-content types. :::

Sending events

You can send search events to your DocSearch index by passing in the insights parameter when creating your DocSearch instance.

<Tabs groupId="language" defaultValue="js" values={[ { label: 'JavaScript', value: 'js', }, { label: 'React', value: 'react', } ] }> 

docsearch({
   // other options
+  insights: true,
});
<DocSearch
  // other options
+  insights={true}
/>

Performance optimization

Preconnect

Improve the loading speed of your initial search request by adding this snippet into your website's <head> section:

<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />

This helps the browser establish a quick connection with Algolia, enhancing user experience, especially on mobile devices.