-
Notifications
You must be signed in to change notification settings - Fork 402
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(website): new documentation (#1048)
Showing
140 changed files
with
8,430 additions
and
21,812 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
module.exports = { | ||
presets: [require.resolve('@docusaurus/core/lib/babel/preset')], | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,258 @@ | ||
--- | ||
title: DocSearch v3 | ||
--- | ||
|
||
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. | ||
|
||
::: | ||
|
||
## 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@alpha | ||
# or | ||
npm install @docsearch/js@alpha | ||
``` | ||
|
||
If you don’t want to use a package manager, you can use a standalone endpoint: | ||
|
||
```html | ||
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@alpha"></script> | ||
``` | ||
|
||
</TabItem> | ||
<TabItem value="react"> | ||
|
||
|
||
```bash | ||
yarn add @docsearch/react@alpha | ||
# or | ||
npm install @docsearch/react@alpha | ||
``` | ||
|
||
If you don’t want to use a package manager, you can use a standalone endpoint: | ||
|
||
```html | ||
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@alpha"></script> | ||
``` | ||
|
||
</TabItem> | ||
|
||
|
||
</Tabs> | ||
|
||
|
||
## Get started | ||
|
||
<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 credentails, you can use ours! | ||
|
||
<Tabs | ||
groupId="language" | ||
defaultValue="js" | ||
values={[ | ||
{ label: 'JavaScript', value: 'js', }, | ||
{ label: 'React', value: 'react', } | ||
] | ||
}> | ||
<TabItem value="js"> | ||
|
||
|
||
```js | ||
docsearch({ | ||
appId: 'BH4D9OD16A', | ||
apiKey: '25626fae796133dc1e734c6bcaaeac3c', | ||
indexName: 'docsearch', | ||
}); | ||
``` | ||
|
||
</TabItem> | ||
|
||
|
||
<TabItem value="react"> | ||
|
||
|
||
```jsx | ||
<DocSearch | ||
appId="BH4D9OD16A" | ||
apiKey="25626fae796133dc1e734c6bcaaeac3c" | ||
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> | ||
|
||
|
||
## 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]: legacy/dropdown | ||
[5]: 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]: api#container | ||
[12]: api | ||
[13]: required-configuration#introduce-global-information-as-meta-tags | ||
[14]: record-extractor#with-custom-variables | ||
[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/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,225 @@ | ||
--- | ||
title: API Reference | ||
--- | ||
|
||
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. | ||
|
||
::: | ||
|
||
<Tabs | ||
groupId="language" | ||
defaultValue="js" | ||
values={[ | ||
{ label: 'JavaScript', value: 'js', }, | ||
{ label: 'React', value: 'react', } | ||
] | ||
}> | ||
<TabItem value="js"> | ||
|
||
|
||
## `container` | ||
|
||
> `type: string | HTMLElement` | **required** | ||
The container for the DocSearch search box. You can either pass a [CSS selector][5] or an [Element][6]. If there are several containers matching the selector, DocSearch picks up the first one. | ||
|
||
## `environment` | ||
|
||
> `type: typeof window` | `default: window` | **optional** | ||
The environment in which your application is running. | ||
|
||
This is useful if you’re using DocSearch in a different context than window. | ||
|
||
## `appId` | ||
|
||
> `type: string` | **required** | ||
Your Algolia application ID. | ||
|
||
## `apiKey` | ||
|
||
> `type: string` | **required** | ||
Your Algolia Search API key. | ||
|
||
## `indexName` | ||
|
||
> `type: string` | **required** | ||
Your Algolia index name. | ||
|
||
## `placeholder` | ||
|
||
> `type: string` | `default: "Search docs" | **optional** | ||
The placeholder of the input of the DocSearch pop-up modal. | ||
|
||
## `searchParameters` | ||
|
||
> `type: SearchParameters` | **optional** | ||
The [Algolia Search Parameters][7]. | ||
|
||
## `transformItems` | ||
|
||
> `type: function` | `default: items => items` | **optional** | ||
Receives the items from the search response, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them. | ||
|
||
```js | ||
docsearch({ | ||
// ... | ||
transformItems(items) { | ||
return items.map((item) => ({ | ||
...item, | ||
content: item.content.toUpperCase(), | ||
})); | ||
}, | ||
}); | ||
``` | ||
|
||
## `hitComponent` | ||
|
||
> `type: ({ hit, children }) => JSX.Element` | `default: Hit` | **optional** | ||
The component to display each item. | ||
|
||
See the [default implementation][8]. | ||
|
||
## `transformSearchClient` | ||
|
||
> `type: function` | `default: searchClient => searchClient` | **optional** | ||
Useful for transforming the [Algolia Search Client][10], for example to [debounce search queries][9] | ||
|
||
## `disableUserPersonalization` | ||
|
||
> `type: boolean` | `default: false` | **optional** | ||
Disable saving recent searches and favorites to the local storage. | ||
|
||
## `initialQuery` | ||
|
||
> `type: string` | **optional** | ||
The search input initial query. | ||
|
||
## `navigator` | ||
|
||
> `type: Navigator` | **optional** | ||
An implementation of [Algolia Autocomplete][1]’s Navigator API to redirect the user when opening a link. | ||
|
||
Learn more on the [Navigator API][11] documentation. | ||
|
||
</TabItem> | ||
|
||
|
||
<TabItem value="react"> | ||
|
||
|
||
## `appId` | ||
|
||
> `type: string` | **required** | ||
Your Algolia application ID. | ||
|
||
## `apiKey` | ||
|
||
> `type: string` | **required** | ||
Your Algolia Search API key. | ||
|
||
## `indexName` | ||
|
||
> `type: string` | **required** | ||
Your Algolia index name. | ||
|
||
## `placeholder` | ||
|
||
> `type: string` | `default: "Search docs" | **optional** | ||
The placeholder of the input of the DocSearch pop-up modal. | ||
|
||
## `searchParameters` | ||
|
||
> `type: SearchParameters` | **optional** | ||
The [Algolia Search Parameters][7]. | ||
|
||
## `transformItems` | ||
|
||
> `type: function` | `default: items => items` | **optional** | ||
Receives the items from the search response, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them. | ||
|
||
```jsx | ||
<DocSearch | ||
// ... | ||
transformItems={(items) => { | ||
return items.map((item) => ({ | ||
...item, | ||
content: item.content.toUpperCase(), | ||
})); | ||
}} | ||
/> | ||
``` | ||
|
||
## `hitComponent` | ||
|
||
> `type: ({ hit, children }) => JSX.Element` | `default: Hit` | **optional** | ||
The component to display each item. | ||
|
||
See the [default implementation][8]. | ||
|
||
## `transformSearchClient` | ||
|
||
> `type: function` | `default: searchClient => searchClient` | **optional** | ||
Useful for transforming the [Algolia Search Client][10], for example to [debounce search queries][9] | ||
|
||
## `disableUserPersonalization` | ||
|
||
> `type: boolean` | `default: false` | **optional** | ||
Disable saving recent searches and favorites to the local storage. | ||
|
||
## `initialQuery` | ||
|
||
> `type: string` | **optional** | ||
The search input initial query. | ||
|
||
## `navigator` | ||
|
||
> `type: Navigator` | **optional** | ||
An implementation of [Algolia Autocomplete][1]’s Navigator API to redirect the user when opening a link. | ||
|
||
Learn more on the [Navigator API][11] documentation. | ||
|
||
</TabItem> | ||
|
||
|
||
</Tabs> | ||
|
||
|
||
[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]: legacy/dropdown | ||
[5]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | ||
[6]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement | ||
[7]: https://www.algolia.com/doc/api-reference/search-api-parameters/ | ||
[8]: https://github.com/algolia/docsearch/blob/next/packages/docsearch-react/src/Hit.tsx | ||
[9]: https://codesandbox.io/s/docsearch-v3-debounced-search-gnx87 | ||
[10]: https://www.algolia.com/doc/api-client/getting-started/what-is-the-api-client/javascript/?client=javascript | ||
[11]: https://www.algolia.com/doc/ui-libraries/autocomplete/core-concepts/keyboard-navigation/ |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,51 @@ | ||
--- | ||
title: Manage your crawls | ||
--- | ||
|
||
import useBaseUrl from '@docusaurus/useBaseUrl'; | ||
|
||
DocSearch comes with the [Algolia Crawler web interface](https://crawler.algolia.com/) that allows you to configure how and when your Algolia index will be populated. | ||
|
||
## Trigger a new crawl | ||
|
||
Head over to the `Overview` section to `start`, `restart` or `pause` your crawls and view a real-time summary. | ||
|
||
<div className="uil-ta-center"> | ||
<img | ||
src={useBaseUrl('img/assets/crawler-overview.png')} | ||
alt="Algolia Crawler creation page" | ||
/> | ||
</div> | ||
|
||
## Monitor your crawls | ||
|
||
The `monitoring` section helps you find crawl errors or improve your search results. | ||
|
||
<div className="uil-ta-center"> | ||
<img | ||
src={useBaseUrl('img/assets/crawler-monitoring.png')} | ||
alt="Algolia Crawler creation page" | ||
/> | ||
</div> | ||
|
||
## Update your config | ||
|
||
The live editor allows you to update your config file and test your URLs (`URL tester`). | ||
|
||
<div className="uil-ta-center"> | ||
<img | ||
src={useBaseUrl('img/assets/crawler-editor.png')} | ||
alt="Algolia Crawler creation page" | ||
/> | ||
</div> | ||
|
||
## Search preview | ||
|
||
From the [`editor`](#update-your-config), you have access to a `Search preview` tab to browse search results with [`DocSearch v3`](/docs/docsearch-v3). | ||
|
||
<div className="uil-ta-center"> | ||
<img | ||
src={useBaseUrl('img/assets/crawler-search-preview.png')} | ||
alt="Algolia Crawler creation page" | ||
/> | ||
</div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,113 @@ | ||
--- | ||
title: Migrating from legacy | ||
--- | ||
|
||
## Introduction | ||
|
||
With this new version of the [DocSearch UI][1], we wanted to go further and provide better tooling for you to create and maintain your config file, and some extra Algolia features that you all have been requesting for a long time! | ||
|
||
## What's new? | ||
|
||
### Scraper | ||
|
||
The DocSearch infrastructure now leverages the [Algolia Crawler][2]. We've teamed up with our friends and created a new [DocSearch helper][4], that extracts records as we were previously doing with our beloved [DocSearch scraper][3]! | ||
|
||
The best part, is that you no longer need to install any tooling on your side if you want to maintain or update your index! | ||
|
||
We now provide [a web interface][7] that will allow you to: | ||
|
||
- Start, schedule and monitor your crawls | ||
- Edit your config file from our live editor | ||
- Test your results directly with [DocSearch v3][1] | ||
|
||
### Algolia application and credentials | ||
|
||
We've received a lot of requests asking for: | ||
|
||
- A way to manage team members | ||
- Browse and see how Algolia records are indexed | ||
- See and subscribe to other Algolia features | ||
|
||
They are now all available, in **your own Algolia application**, for free :D | ||
|
||
## Config file key mapping | ||
|
||
Below are the keys that can be found in the [`legacy` DocSearch configs][14] and their translation to an [Algolia Crawler config][16]. More detailed documentation of the Algolia Crawler can be found on the [the official documentation][15] | ||
|
||
| `legacy` | `current` | description | | ||
| --- | --- | --- | | ||
| `start_urls` | [`startUrls`][20] | Now accepts URLs only, see [`helpers.docsearch`][30] to handle custom variables | | ||
| `page_rank` | [`pageRank`][31] | Can be added to the `recordProps` in [`helpers.docsearch`][30] | | ||
| `js_render` | [`renderJavaScript`][21] | Unchanged | | ||
| `js_wait` | [`renderJavascript.waitTime`][22] | See documentation of [`renderJavaScript`][21] | | ||
| `index_name` | **removed**, see [`actions`][23] | Handled directly in the [`actions`][23] | | ||
| `sitemap_urls` | [`sitemaps`][24] | Unchanged | | ||
| `stop_urls` | [`exclusionPatterns`][25] | Supports [`micromatch`][27] | | ||
| `selectors_exclude` | **removed** | Should be handled in the [`recordExtractor`][28] and [`helpers.docsearch`][29] | | ||
| `custom_settings` | [`initialIndexSettings`][26] | Unchanged | | ||
| `scrape_start_urls` | **removed** | Can be handled with [`exclusionPatterns`][25] | | ||
| `strip_chars` | **removed** | `#` are removed automatically from anchor links, edge cases should be handled in the [`recordExtractor`][28] and [`helpers.docsearch`][29] | | ||
| `conversation_id` | **removed** | Not needed anymore | | ||
| `nb_hits` | **removed** | Not needed anymore | | ||
| `sitemap_alternate_links` | **removed** | Not needed anymore | | ||
| `stop_content` | **removed** | Should be handled in the [`recordExtractor`][28] and [`helpers.docsearch`][29] | | ||
|
||
## FAQ | ||
|
||
### Migration seems to have started, but I don't have received any emails | ||
|
||
Due to the large number of indices DocSearch has, we need to migrate configs in small incremental batches. | ||
|
||
If you have not received a migration mail yet, don't worry, your turn will come! | ||
|
||
### What do I need to do to migrate? | ||
|
||
Nothing! | ||
|
||
We handle all the migration on our side, [your existing config file][11] will be migrated to an [Algolia Crawler config][12], crawls will be started and scheduled for you, your Algolia application will be ready to go, and your Algolia index populated with your website content! | ||
|
||
### What do I need to update to make the migration work? | ||
|
||
We've tried to make the migration as seamless as possible for you, so **all you need to update is your frontend integration** with the new credentials you've received by mail, or directly from the [Algolia dashboard][13]! | ||
|
||
### What should I do with my legacy config and credentials? | ||
|
||
Your [legacy config][11] will be parsed to a [Crawler config][12], please use [the dedicated web interface][7] to make any changes if you already received your access! | ||
|
||
Your credentials will remain available, but **once all the existing configs have been migrated, we will stop the daily crawl jobs**. | ||
|
||
### Are the [`docsearch-scraper`][8] and [`docsearch-configs`][9] repository still maintained? | ||
|
||
At the time you are reading this, the migration hasn't been completed, so yes they are still maintained. | ||
|
||
**Once the migration has been completed:** | ||
|
||
- The [`docsearch-scraper`][8] will be archived and not maintained in favor of our [Algolia Crawler][2], you'll still be able to use our [run your own][3] solution if you want! | ||
- The [`docsearch-configs`][9] repository will be archived and and host **all** of [the existing and active **legacy** DocSearch config file][11], and [their parsed version][12]. You can get a preview [on this branch][10]. | ||
|
||
[1]: DocSearch-v3 | ||
[2]: https://www.algolia.com/products/search-and-discovery/crawler/ | ||
[3]: legacy/run-your-own | ||
[4]: record-extractor | ||
[7]: https://crawler.algolia.com/ | ||
[8]: https://github.com/algolia/docsearch-scraper | ||
[9]: https://github.com/algolia/docsearch-configs | ||
[10]: https://github.com/algolia/docsearch-configs/tree/feat/crawler | ||
[11]: https://github.com/algolia/docsearch-configs | ||
[12]: https://github.com/algolia/docsearch-configs/tree/feat/crawler/crawler-configs | ||
[13]: https://www.algolia.com/dashboard | ||
[14]: /docs/legacy/config-file | ||
[15]: https://www.algolia.com/doc/tools/crawler/getting-started/overview/ | ||
[16]: https://www.algolia.com/doc/tools/crawler/apis/configuration/ | ||
[20]: https://www.algolia.com/doc/tools/crawler/apis/configuration/start-urls/ | ||
[21]: https://www.algolia.com/doc/tools/crawler/apis/configuration/render-java-script/ | ||
[22]: https://www.algolia.com/doc/tools/crawler/apis/configuration/render-java-script/#parameter-param-waittime | ||
[23]: https://www.algolia.com/doc/tools/crawler/apis/configuration/actions/#parameter-param-indexname | ||
[24]: https://www.algolia.com/doc/tools/crawler/apis/configuration/sitemaps/ | ||
[25]: https://www.algolia.com/doc/tools/crawler/apis/configuration/exclusion-patterns/ | ||
[26]: https://www.algolia.com/doc/tools/crawler/apis/configuration/initial-index-settings/ | ||
[27]: https://github.com/micromatch/micromatch | ||
[28]: https://www.algolia.com/doc/tools/crawler/apis/configuration/actions/#parameter-param-recordextractor | ||
[29]: record-extractor | ||
[30]: record-extractor#with-custom-variables | ||
[31]: record-extractor#pagerank |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,240 @@ | ||
--- | ||
title: Record Extractor | ||
--- | ||
|
||
:::info | ||
|
||
The following content is for **[DocSearch v3][2]** and **[its new infrastructure][5]**. If you are using **[DocSearch v2][3]** or the **[docsearch-scraper][6]**, see the **[legacy][4]** documentation. | ||
|
||
::: | ||
|
||
## Introduction | ||
|
||
:::info | ||
|
||
This documentation will only contain information regarding the **helpers.docsearch** method, see **[Algolia Crawler Documentation][7]** for more information on the **[Algolia Crawler][8]**. | ||
|
||
::: | ||
|
||
Pages are extracted by a [`recordExtractor`][9]. These extractors are assigned to [`actions`][12] via the [`recordExtractor`][9] parameter. This parameter links to a function that returns the data you want to index, organized in a array of JSON objects. | ||
|
||
_The helpers are a collection of functions to help you extract content and generate Algolia records._ | ||
|
||
### Useful links | ||
|
||
- [Extracting records with the Algolia Crawler][11] | ||
- [`recordExtractor` parameters][10] | ||
|
||
## Usage | ||
|
||
The most common way to use the DocSearch helper, is to return its result to the [`recordExtractor`][9] function. | ||
|
||
```js | ||
recordExtractor: ({ helpers }) => { | ||
return helpers.docsearch({ | ||
recordProps: { | ||
lvl0: { | ||
selectors: "header h1", | ||
}, | ||
lvl1: "article h2", | ||
lvl2: "article h3", | ||
lvl3: "article h4", | ||
lvl4: "article h5", | ||
lvl5: "article h6", | ||
content: "main p, main li", | ||
}, | ||
}); | ||
}, | ||
``` | ||
|
||
## Complex extractors | ||
|
||
### Using the Cheerio instance (`$`) | ||
|
||
You can also use the provided [`Cheerio instance ($)`][14] to exclude content from the DOM: | ||
|
||
```js | ||
recordExtractor: ({ $, helpers }) => { | ||
// Removing DOM elements we don't want to crawl | ||
$(".my-warning-message").remove(); | ||
|
||
return helpers.docsearch({ | ||
recordProps: { | ||
lvl0: { | ||
selectors: "header h1", | ||
}, | ||
lvl1: "article h2", | ||
lvl2: "article h3", | ||
lvl3: "article h4", | ||
lvl4: "article h5", | ||
lvl5: "article h6", | ||
content: "main p, main li", | ||
}, | ||
}); | ||
}, | ||
``` | ||
|
||
### With fallback DOM selectors | ||
|
||
Each `lvlX` and `content` supports fallback selectors as an array of string, which allows for robust config files: | ||
|
||
```js | ||
recordExtractor: ({ $, helpers }) => { | ||
return helpers.docsearch({ | ||
recordProps: { | ||
// `.exists h1` will be selected if `.exists-probably h1` does not exists. | ||
lvl0: { | ||
selectors: [".exists-probably h1", ".exists h1"], | ||
} | ||
lvl1: "article h2", | ||
lvl2: "article h3", | ||
lvl3: "article h4", | ||
lvl4: "article h5", | ||
lvl5: "article h6", | ||
// `.exists p, .exists li` will be selected. | ||
content: [ | ||
".does-not-exists p, .does-not-exists li", | ||
".exists p, .exists li", | ||
], | ||
}, | ||
}); | ||
}, | ||
``` | ||
|
||
### With custom variables | ||
|
||
Custom variables are useful to filter content in the frontend (`version`, `lang`, etc.). | ||
|
||
_These selectors also support [`defaultValue`](#with-raw-text-defaultvalue) and [fallback selectors](#with-fallback-dom-selectors)_ | ||
|
||
```js | ||
recordExtractor: ({ helpers }) => { | ||
return helpers.docsearch({ | ||
recordProps: { | ||
lvl0: { | ||
selectors: "header h1", | ||
}, | ||
lvl1: "article h2", | ||
lvl2: "article h3", | ||
lvl3: "article h4", | ||
lvl4: "article h5", | ||
lvl5: "article h6", | ||
content: "main p, main li", | ||
// The variables below can be used to filter your search | ||
foo: ".bar", | ||
language: { | ||
// It also supports the fallback DOM selectors syntax! | ||
selectors: ".does-not-exists", | ||
// Since custom variables are used for filtering, we allow sending | ||
// multiple raw values | ||
defaultValue: ["en", "en-US"], | ||
}, | ||
version: { | ||
// You can send raw values without `selectors` | ||
defaultValue: ["latest", "stable"], | ||
}, | ||
}, | ||
}); | ||
}, | ||
``` | ||
|
||
The `version`, `lang` and `foo` attribute of these records will be : | ||
|
||
```json | ||
foo: "valueFromBarSelector", | ||
language: ["en", "en-US"], | ||
version: ["latest", "stable"] | ||
``` | ||
|
||
You can now use them to [filter your search in the frontend][16] | ||
|
||
### With raw text (`defaultValue`) | ||
|
||
The `lvl0` and [custom variables][13] selectors also accepts a fallback raw value: | ||
|
||
```js | ||
recordExtractor: ({ $, helpers }) => { | ||
return helpers.docsearch({ | ||
recordProps: { | ||
lvl0: { | ||
// It also supports the fallback DOM selectors syntax! | ||
selectors: ".exists-probably h1", | ||
defaultValue: "myRawTextIfDoesNotExists", | ||
}, | ||
lvl1: "article h2", | ||
lvl2: "article h3", | ||
lvl3: "article h4", | ||
lvl4: "article h5", | ||
lvl5: "article h6", | ||
content: "main p, main li", | ||
// The variables below can be used to filter your search | ||
language: { | ||
// It also supports the fallback DOM selectors syntax! | ||
selectors: ".exists-probably .language", | ||
// Since custom variables are used for filtering, we allow sending | ||
// multiple raw values | ||
defaultValue: ["en", "en-US"], | ||
}, | ||
}, | ||
}); | ||
}, | ||
``` | ||
|
||
## `recordProps` API Reference | ||
|
||
### `lvl0` | ||
|
||
> `type: Lvl0` | **required** | ||
```ts | ||
type Lvl0 = { | ||
selectors: string | string[]; | ||
defaultValue?: string; | ||
}; | ||
``` | ||
|
||
### `lvl1`, `content` | ||
|
||
> `type: string | string[]` | **required** | ||
### `lvl2`, `lvl3`, `lvl4`, `lvl5`, `lvl6` | ||
|
||
> `type: string | string[]` | **optional** | ||
### `pageRank` | ||
|
||
> `type: string` | **optional** | ||
### Custom variables (`[k: string]`) | ||
|
||
> `type: string | string[] | CustomVariable` | **optional** | ||
```ts | ||
type CustomVariable = | ||
| { | ||
defaultValue: string | string[]; | ||
} | ||
| { | ||
selectors: string | string[]; | ||
defaultValue?: string | string[]; | ||
}; | ||
``` | ||
|
||
Contains values that can be used as [`facetFilters`][15] | ||
|
||
[1]: DocSearch-v3 | ||
[2]: https://github.com/algolia/docsearch/ | ||
[3]: https://github.com/algolia/docsearch/tree/master | ||
[4]: /docs/legacy/dropdown | ||
[5]: /docs/migrating-from-legacy | ||
[6]: /docs/legacy/run-your-own | ||
[7]: https://www.algolia.com/doc/tools/crawler/getting-started/overview/ | ||
[8]: https://www.algolia.com/products/search-and-discovery/crawler/ | ||
[9]: https://www.algolia.com/doc/tools/crawler/apis/configuration/actions/#parameter-param-recordextractor | ||
[10]: https://www.algolia.com/doc/tools/crawler/apis/configuration/actions/#parameter-param-recordextractor-2 | ||
[11]: https://www.algolia.com/doc/tools/crawler/guides/extracting-data/#extracting-records | ||
[12]: https://www.algolia.com/doc/tools/crawler/apis/configuration/actions/ | ||
[13]: /docs/record-extractor#with-custom-variables | ||
[14]: https://cheerio.js.org/ | ||
[15]: https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/ | ||
[16]: DocSearch-v3#filtering-your-search |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,208 @@ | ||
--- | ||
title: Required configuration | ||
--- | ||
|
||
This section, gives you the best practices to optimize our crawl. Adopting this following specification is required to let our crawler build the best experience from your website. You will need to update your website and follow these rules. | ||
|
||
:::info | ||
|
||
If your website is generated, thanks to one of [our supported tools][1], you do not need to change your website as it is already compliant with our requirements. | ||
|
||
::: | ||
|
||
## The generic configuration example | ||
|
||
You can find the default DocSearch config template below and tweak it with some examples from our [`complex extractors` section][12]. | ||
|
||
If you are using one of [our integrations][13], please see [the templates page][11]. | ||
|
||
<details><summary>docsearch-default.js</summary> | ||
<div> | ||
|
||
|
||
```js | ||
new Crawler({ | ||
appId: 'YOUR_APP_ID', | ||
apiKey: 'YOUR_API_KEY', | ||
startUrls: ['https://YOUR_START_URL.io/'], | ||
sitemaps: ['https://YOUR_START_URL.io/sitemap.xml'], | ||
actions: [ | ||
{ | ||
indexName: 'YOUR_INDEX_NAME', | ||
pathsToMatch: ['https://YOUR_START_URL.io/**'], | ||
recordExtractor: ({ helpers }) => { | ||
return helpers.docsearch({ | ||
recordProps: { | ||
lvl0: { | ||
selectors: '', | ||
defaultValue: 'Documentation', | ||
}, | ||
lvl1: 'header h1', | ||
lvl2: 'article h2', | ||
lvl3: 'article h3', | ||
lvl4: 'article h4', | ||
lvl5: 'article h5', | ||
lvl6: 'article h6', | ||
content: 'article p, article li', | ||
}, | ||
}); | ||
}, | ||
}, | ||
], | ||
initialIndexSettings: { | ||
YOUR_INDEX_NAME: { | ||
attributesForFaceting: ['type'], | ||
attributesToRetrieve: [ | ||
'hierarchy', | ||
'content', | ||
'anchor', | ||
'url', | ||
'url_without_anchor', | ||
'type', | ||
], | ||
attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'], | ||
attributesToSnippet: ['content:10'], | ||
camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'], | ||
searchableAttributes: [ | ||
'unordered(hierarchy_radio_camel.lvl0)', | ||
'unordered(hierarchy_radio.lvl0)', | ||
'unordered(hierarchy_radio_camel.lvl1)', | ||
'unordered(hierarchy_radio.lvl1)', | ||
'unordered(hierarchy_radio_camel.lvl2)', | ||
'unordered(hierarchy_radio.lvl2)', | ||
'unordered(hierarchy_radio_camel.lvl3)', | ||
'unordered(hierarchy_radio.lvl3)', | ||
'unordered(hierarchy_radio_camel.lvl4)', | ||
'unordered(hierarchy_radio.lvl4)', | ||
'unordered(hierarchy_radio_camel.lvl5)', | ||
'unordered(hierarchy_radio.lvl5)', | ||
'unordered(hierarchy_radio_camel.lvl6)', | ||
'unordered(hierarchy_radio.lvl6)', | ||
'unordered(hierarchy_camel.lvl0)', | ||
'unordered(hierarchy.lvl0)', | ||
'unordered(hierarchy_camel.lvl1)', | ||
'unordered(hierarchy.lvl1)', | ||
'unordered(hierarchy_camel.lvl2)', | ||
'unordered(hierarchy.lvl2)', | ||
'unordered(hierarchy_camel.lvl3)', | ||
'unordered(hierarchy.lvl3)', | ||
'unordered(hierarchy_camel.lvl4)', | ||
'unordered(hierarchy.lvl4)', | ||
'unordered(hierarchy_camel.lvl5)', | ||
'unordered(hierarchy.lvl5)', | ||
'unordered(hierarchy_camel.lvl6)', | ||
'unordered(hierarchy.lvl6)', | ||
'content', | ||
], | ||
distinct: true, | ||
attributeForDistinct: 'url', | ||
customRanking: [ | ||
'desc(weight.pageRank)', | ||
'desc(weight.level)', | ||
'asc(weight.position)', | ||
], | ||
ranking: [ | ||
'words', | ||
'filters', | ||
'typo', | ||
'attribute', | ||
'proximity', | ||
'exact', | ||
'custom', | ||
], | ||
highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">', | ||
highlightPostTag: '</span>', | ||
minWordSizefor1Typo: 3, | ||
minWordSizefor2Typos: 7, | ||
allowTyposOnNumericTokens: false, | ||
minProximity: 1, | ||
ignorePlurals: true, | ||
advancedSyntax: true, | ||
attributeCriteriaComputedByMinProximity: true, | ||
removeWordsIfNoResults: 'allOptional', | ||
separatorsToIndex: '_', | ||
}, | ||
}, | ||
}); | ||
``` | ||
|
||
</div> | ||
</details> | ||
|
||
|
||
### Overview of a clear layout | ||
|
||
A website implementing these good practises will look simple and crystal clear. It can have this following aspect: | ||
|
||
<img | ||
src="https://docsearch.algolia.com/img/assets/recommended-layout.png" | ||
alt="Recommended layout for your page" | ||
/> | ||
|
||
The main blue element will be your `.DocSearch-content` container. More details in the following guidelines. | ||
|
||
### Use the right classes as [`recordProps`][2] | ||
|
||
You can add some specific static classes to help us find your content role. These classes can not involve any style changes. These dedicated classes will help us to create a great learn-as-you-type experience from your documentation. | ||
|
||
- Add a static class `DocSearch-content` to the main container of your textual content. Most of the time, this tag is a `<main>` or an `<article>` HTML element. | ||
|
||
- Every searchable `lvl` element outside this main documentation container (for instance in a sidebar) must be a `global` selector. They will be globally picked up and injected to every record built from your page. Be careful, the level value matters and every matching element must have an increasing level along the HTML flow. A level `X` (for `lvlX`) should appear after a level `Y` while `X > Y`. | ||
|
||
- `lvlX` selectors should use the standard title tags like `h1`, `h2`, `h3`, etc. You can also use static classes. Set a unique `id` or `name` attribute to these elements as detailed below. | ||
|
||
- Every DOM element matching the `lvlX` selectors must have a unique `id` or `name` attribute. This will help the redirection to directly scroll down to the exact place of the matching elements. These attributes define the right anchor to use. | ||
|
||
- Every textual element (recordProps `content`) must be wrapped in a `<p>` or `<li>` tag. This content must be atomic and split into small entities. Be careful to never nest one matching element into another one as it will create duplicates. | ||
|
||
- Stay consistent and do not forget that we need to have some consistency along the HTML flow. | ||
|
||
## Introduce global information as meta tags | ||
|
||
Our crawler automatically extracts information from our DocSearch specific meta tags: | ||
|
||
```html | ||
<meta name="docsearch:language" content="en" /> | ||
<meta name="docsearch:version" content="1.0.0" /> | ||
``` | ||
|
||
The crawl adds the `content` value of these `meta` tags to all records extracted from the page. The meta tags `name` must follow the `docsearch:$NAME` pattern. `$NAME` is the name of the attribute set to all records. | ||
|
||
The `docsearch:version` meta tag can be a set [of comma-separated tokens][5], each of which is a version relevant to the page. These tokens must be compliant with [the SemVer specification][6] or only contain alphanumeric characters (e.g. `latest`, `next`, etc.). As facet filters, these version tokens are case-insensitive. | ||
|
||
For example, all records extracted from a page with the following meta tag: | ||
|
||
```html | ||
<meta name="docsearch:version" content="2.0.0-alpha.62,latest" /> | ||
``` | ||
|
||
The `version` attribute of these records will be : | ||
|
||
```json | ||
version:["2.0.0-alpha.62", "latest"] | ||
``` | ||
|
||
You can then [transform these attributes as `facetFilters`][3] to [filter over them from the UI][10]. | ||
|
||
## Nice to have | ||
|
||
- Your website should have [an updated sitemap][7]. This is key to let our crawler know what should be updated. Do not worry, we will still crawl your website and discover embedded hyperlinks to find your great content. | ||
|
||
- Every page needs to have their full context available. Using global elements might help (see above). | ||
|
||
- Make sure your documentation content is also available without JavaScript rendering on the client-side. If you absolutely need JavaScript turned on, you need to [set `renderJavaScript: true` in your configuration][8]. | ||
|
||
Any questions? [Send us an email][9]. | ||
|
||
[1]: integrations | ||
[2]: record-extractor#recordProps-api-reference | ||
[3]: https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/ | ||
[5]: https://html.spec.whatwg.org/dev/common-microsyntaxes.html#comma-separated-tokens | ||
[6]: https://semver.org/ | ||
[7]: https://www.sitemaps.org/ | ||
[8]: https://www.algolia.com/doc/tools/crawler/apis/configuration/render-java-script/ | ||
[9]: mailto:DocSearch@algolia.com | ||
[10]: DocSearch-v3#filtering-your-search | ||
[11]: templates | ||
[12]: record-extractor#complex-extractors | ||
[13]: integrations |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,54 @@ | ||
--- | ||
title: Styling | ||
--- | ||
|
||
:::info | ||
|
||
The following content is for **[DocSearch v3][2]**. If you are using **[DocSearch v2][3]**, see the **[legacy][4]** documentation. | ||
|
||
::: | ||
|
||
:::caution | ||
|
||
This documentation is in progress. | ||
|
||
::: | ||
|
||
## Introduction | ||
|
||
DocSearch v3 comes with a theme package called `@docsearch/css`, which offers a sleek out of the box theme! | ||
|
||
:::note | ||
|
||
You don't need to install this package if you already have [`@docsearch/js`][1] or [`@docsearch/react`][1] installed! | ||
|
||
::: | ||
|
||
## Installation | ||
|
||
```bash | ||
yarn add @docsearch/css@alpha | ||
# or | ||
npm install @docsearch/css@alpha | ||
``` | ||
|
||
If you don’t want to use a package manager, you can use a standalone endpoint: | ||
|
||
```html | ||
<script src="https://cdn.jsdelivr.net/npm/@docsearch/css@alpha"></script> | ||
``` | ||
|
||
## Files | ||
|
||
``` | ||
@docsearch/css | ||
├── dist/style.css # all styles | ||
├── dist/_variables.css # CSS variables | ||
├── dist/button.css # CSS for the button | ||
└── dist/modal.css # CSS for the modal | ||
``` | ||
|
||
[1]: DocSearch-v3 | ||
[2]: https://github.com/algolia/docsearch/ | ||
[3]: https://github.com/algolia/docsearch/tree/master | ||
[4]: legacy/dropdown |
This file was deleted.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.