19c1ef9192
* feat(v4): add new UI (#2555) * feat: add new footer ui * feat: add new search box ui * feat: add searchbox actions * feat: add start screen * feat: add no results screen * feat: add new card ui * feat: add new icons * feat: add new key press class * fix: cypress tests * fix: circleci * fix: circleci * fix: close aria label * fix: circleci * fix: remove unused classes * fix: circleci * feat: update version * feat: add new dark mode ui * fix: colors * fix: design review * fix: hit title length * fix: improve accessibility * fix: ci * chore: increase bundle size threshold * fix: css * feat(v4): ask-ai foundations ✨ (#2574) * feat(v4): docsearch askAI context (#2587) * fix(v4): ask ai updates (#2654) * feat(v4): update beta documentation (#2659) * chore: release v4.0.0-beta.0 (#2660) * fix: make release run on branches like v4 * chore: release v4.0.0-beta.0 * hotfix: closing on askai error * chore: release v4.0.0-beta.1 (#2661) * fix: add a section on models * fix: update to `<package>@beta` * feat(docsearch-website): Updated docs (#2662) * feat(v4): update the landing page (#2665) * fix: beta in readme * feat: added glow around the search bar and a little copy above the keyboard * feat: add glow around the search bar and copy above the keyboard * fix: Add more styling * fix: polishing v4 (#2667) * chore: release v4.0.0-beta.2 (#2668) * fix: update docusaurus tarballs * fix(website): update docusaurus tarballs * fix: mobile search bar --------- Co-authored-by: Vasco Bettencourt <32492444+vascobettencourt@users.noreply.github.com> Co-authored-by: Natan Yagudayev <natanyagudayev@gmail.com>
301 lines
6.7 KiB
Text
301 lines
6.7 KiB
Text
---
|
||
title: Getting Started
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
|
||
:::info
|
||
|
||
The following content is for **[DocSearch v3][2]**.
|
||
If you are using **[DocSearch v2][3]**, see the **[legacy][4]** documentation.
|
||
|
||
If you are looking for **DocSearch v4**, see the documentation **[here][17]**.
|
||
|
||
:::
|
||
|
||
## Introduction
|
||
|
||
DocSearch v3 is built on top of the latest version of [Algolia Autocomplete][1], which provides better accessibility, increased responsiveness, themability, a better built-in design, and customizability under low-network conditions.
|
||
|
||
This version has been rewritten in React, and now exposes React components. The vanilla JavaScript version is based on the React version with an alias to Preact.
|
||
|
||
### Stable version
|
||
|
||
With the recent release of the stable version of [Algolia Autocomplete][1], and the huge adoption of DocSearch v3, we will start working on a stable release!
|
||
|
||
Thanks to all the Alpha testers, and to [all the integrations][5] who already support it!
|
||
|
||
## Installation
|
||
|
||
DocSearch packages are available on the [npm][10] registry.
|
||
|
||
<Tabs
|
||
groupId="language"
|
||
defaultValue="js"
|
||
values={[
|
||
{ label: 'JavaScript', value: 'js', },
|
||
{ label: 'React', value: 'react', }
|
||
]
|
||
}>
|
||
<TabItem value="js">
|
||
|
||
```bash
|
||
yarn add @docsearch/js@3
|
||
# or
|
||
npm install @docsearch/js@3
|
||
```
|
||
|
||
### Without package manager
|
||
|
||
If you don't want to use a package manager, you can add the CSS to the `<head>` of your website:
|
||
|
||
```html
|
||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
|
||
```
|
||
|
||
And the JavaScript at the end of your `<body>`:
|
||
|
||
```html
|
||
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="react">
|
||
|
||
```bash
|
||
yarn add @docsearch/react@3
|
||
# or
|
||
npm install @docsearch/react@3
|
||
```
|
||
|
||
### Without package manager
|
||
|
||
If you don't want to use a package manager, you can add the CSS to the `<head>` of your website:
|
||
|
||
```html
|
||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
|
||
```
|
||
|
||
And the JavaScript at the end of your `<body>`:
|
||
|
||
```html
|
||
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@3"></script>
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
### Improve first query speed
|
||
|
||
You can hint the browser to improve the speed of the first query by adding a `preconnect`, see [#preconnect](#preconnect)
|
||
|
||
## Implementation
|
||
|
||
<Tabs
|
||
groupId="language"
|
||
defaultValue="js"
|
||
values={[
|
||
{ label: 'JavaScript', value: 'js', },
|
||
{ label: 'React', value: 'react', }
|
||
]
|
||
}>
|
||
<TabItem value="js">
|
||
|
||
To get started, you need a [`container`][11] for your DocSearch component to go in. If you don’t have one already, you can insert one into your markup:
|
||
|
||
```html
|
||
<div id="docsearch"></div>
|
||
```
|
||
|
||
Then, insert DocSearch into it by calling the [`docsearch`][12] function and providing the container. It can be a [CSS selector][6] or an [Element][7].
|
||
|
||
Make sure to provide a [`container`][11] (for example, a `div`), not an `input`. DocSearch generates a fully accessible search box for you.
|
||
|
||
```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',
|
||
});
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="react">
|
||
|
||
DocSearch generates a fully accessible search box for you.
|
||
|
||
```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;
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
### Testing
|
||
|
||
If you're eager to test DocSearch v3 and can't wait to receive your credentials, you can use ours!
|
||
|
||
<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',
|
||
});
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="react">
|
||
|
||
```jsx
|
||
<DocSearch
|
||
appId="PMZUYBQDAK"
|
||
apiKey="24b09689d5b4223813d9b8e48563c8f6"
|
||
indexName="docsearch"
|
||
/>
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
### Filtering your search
|
||
|
||
If your website supports [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>
|
||
|
||
### 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">
|
||
|
||
```js
|
||
docsearch({
|
||
searchParameters: {
|
||
facetFilters: ['language:en', 'version:1.0.0'],
|
||
},
|
||
insights: true,
|
||
});
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="react">
|
||
|
||
```jsx
|
||
<DocSearch
|
||
searchParameters={{
|
||
facetFilters: ['language:en', 'version:1.0.0'],
|
||
}}
|
||
insights
|
||
/>
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
## Performance optimization
|
||
|
||
### Preconnect
|
||
|
||
By adding this snippet to the `head` of your website, you can hint the browser that the website will load data from Algolia, and allows it to preconnect to the DocSearch cluster. It makes the first query faster, especially on mobile.
|
||
|
||
```html
|
||
<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />
|
||
```
|
||
|
||
[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
|
||
[16]: https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/#facetfilters
|
||
[15]: https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/
|
||
[17]: /docs/docsearch
|