4f68ebbc06
* feat(docusaurus-adapter): Support docsearch key and adapter docs * chore(release): include docusaurus adapter in shipjs publish list * chore(docusaurus-adapter): remove libtmp and pin initial version * fix: issue with footer * fix: contextuals * fix all ts errors * fix: lint * fix lint
390 lines
9.1 KiB
Text
390 lines
9.1 KiB
Text
---
|
|
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][1], DocSearch v4 ensures a seamless integration trusted by leading documentation sites worldwide.
|
|
|
|
## Installation
|
|
|
|
> Looking for the Composable API documentation? You can find it [here][17].
|
|
|
|
DocSearch packages are available on the [npm registry][10].
|
|
|
|
### Docusaurus users
|
|
|
|
If your docs site is powered by Docusaurus, use [`@docsearch/docusaurus-adapter`](/docs/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', }
|
|
]
|
|
}>
|
|
<TabItem value="js">
|
|
|
|
```bash
|
|
yarn add @docsearch/js@4
|
|
# or with npm
|
|
npm install @docsearch/js@4
|
|
```
|
|
|
|
### Without package manager
|
|
|
|
Include CSS in your website's `<head>`
|
|
|
|
```html
|
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
|
|
```
|
|
|
|
And the JavaScript at the end of your `<body>`:
|
|
|
|
```html
|
|
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="react">
|
|
|
|
```bash
|
|
yarn add @docsearch/react@4
|
|
# or
|
|
npm install @docsearch/react@4
|
|
```
|
|
|
|
### Without package manager
|
|
|
|
Include CSS in your website's `<head>`:
|
|
|
|
```html
|
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
|
|
```
|
|
|
|
And the JavaScript at the end of your `<body>`:
|
|
|
|
```html
|
|
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@4"></script>
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
### Optimize first query performance
|
|
|
|
Enhance your users' first search experience by using `preconnect`, see [Performance optimization](#preconnect) below
|
|
|
|
## Implementation
|
|
|
|
<Tabs
|
|
groupId="language"
|
|
defaultValue="js"
|
|
values={[
|
|
{ label: 'JavaScript', value: 'js', },
|
|
{ label: 'React', value: 'react', }
|
|
]
|
|
}>
|
|
<TabItem value="js">
|
|
|
|
DocSearch requires a dedicated container in your HTML
|
|
|
|
```html
|
|
<div id="docsearch"></div>
|
|
```
|
|
|
|
Initialize DocSearch by passing your container:
|
|
|
|
```js app.js
|
|
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.
|
|
|
|
</TabItem>
|
|
|
|
<TabItem value="react">
|
|
|
|
Integrating DocSearch into your React app is straightforward:
|
|
|
|
```jsx App.js
|
|
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.
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
### 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', }
|
|
]
|
|
}>
|
|
<TabItem value="js">
|
|
|
|
```js
|
|
docsearch({
|
|
appId: 'PMZUYBQDAK',
|
|
apiKey: '24b09689d5b4223813d9b8e48563c8f6',
|
|
indexName: 'docsearch',
|
|
askAi: 'askAIDemo',
|
|
});
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
<TabItem value="react">
|
|
|
|
```jsx
|
|
<DocSearch
|
|
appId="PMZUYBQDAK"
|
|
apiKey="24b09689d5b4223813d9b8e48563c8f6"
|
|
indexName="docsearch"
|
|
askAi="askAIDemo"
|
|
/>
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
Or use our new dedicated [DocSearch Playground](https://community.algolia.com/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.
|
|
|
|
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, or search parameters):
|
|
|
|
<Tabs groupId="askai-format" defaultValue="string" values={[{ label: 'String', value: 'string' }, { label: 'Object', value: 'object' }]}>
|
|
<TabItem value="string">
|
|
|
|
```js
|
|
docsearch({
|
|
appId: 'YOUR_APP_ID',
|
|
indexName: 'YOUR_INDEX_NAME',
|
|
apiKey: 'YOUR_SEARCH_API_KEY',
|
|
askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
|
|
});
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="object">
|
|
|
|
```js
|
|
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
|
|
},
|
|
});
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
- 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](https://dashboard.algolia.com) in the Ask AI section.
|
|
|
|
### Filtering search results
|
|
|
|
#### Keyword search
|
|
|
|
If your website uses [DocSearch meta tags][13] or if you've added [custom variables to your config][14], you'll be able to use the [`facetFilters`][16] option to scope your search results to a [`facet`][15]
|
|
|
|
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', }
|
|
]
|
|
}>
|
|
<TabItem value="js">
|
|
|
|
```js
|
|
docsearch({
|
|
searchParameters: {
|
|
facetFilters: ['language:en', 'version:1.0.0'],
|
|
},
|
|
});
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
<TabItem value="react">
|
|
|
|
```jsx
|
|
<DocSearch
|
|
searchParameters={{
|
|
facetFilters: ['language:en', 'version:1.0.0'],
|
|
}}
|
|
/>
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
#### 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', }
|
|
]
|
|
}>
|
|
<TabItem value="js">
|
|
```js
|
|
docsearch({
|
|
askAi: {
|
|
assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
|
|
searchParameters: {
|
|
facetFilters: ['language:en', 'version:1.0.0'],
|
|
},
|
|
},
|
|
});
|
|
```
|
|
</TabItem>
|
|
|
|
<TabItem value="react">
|
|
```jsx
|
|
<DocSearch
|
|
askAi={{
|
|
assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
|
|
searchParameters: {
|
|
facetFilters: ['language:en', 'version:1.0.0'],
|
|
},
|
|
}}
|
|
/>
|
|
```
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
:::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', }
|
|
]
|
|
}>
|
|
<TabItem value="js">
|
|
|
|
```diff
|
|
docsearch({
|
|
// other options
|
|
+ insights: true,
|
|
});
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
<TabItem value="react">
|
|
|
|
```diff
|
|
<DocSearch
|
|
// other options
|
|
+ insights={true}
|
|
/>
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
## Performance optimization
|
|
|
|
### Preconnect
|
|
|
|
Improve the loading speed of your initial search request by adding this snippet into your website's `<head>` section:
|
|
|
|
```html
|
|
<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.
|
|
|
|
[1]: https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/
|
|
[2]: https://github.com/algolia/docsearch/
|
|
[3]: https://github.com/algolia/docsearch/tree/master
|
|
[4]: /docs/legacy/dropdown
|
|
[5]: /docs/integrations
|
|
[6]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
|
|
[7]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
|
|
[8]: https://codesandbox.io/s/docsearch-js-v3-playground-z9oxj
|
|
[9]: https://codesandbox.io/s/docsearch-react-v3-playground-619yg
|
|
[10]: https://www.npmjs.com/
|
|
[11]: /docs/api#container
|
|
[12]: /docs/api
|
|
[13]: /docs/required-configuration#introduce-global-information-as-meta-tags
|
|
[14]: /docs/record-extractor#indexing-content-for-faceting
|
|
[15]: https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/
|
|
[16]: https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/#facetfilters
|
|
[17]: /docs/composable-api
|