docs(website): add FAQ questions, better Crawler examples (#1157)
This commit is contained in:
Clément Vannicatte
GitHub
parent
10c5b2ea14
commit
c12b5ce1a3
4 changed files with 1431 additions and 606 deletions
|
|
@ -2,6 +2,9 @@
|
|||
title: Migrating from legacy
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## 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!
|
||||
|
|
@ -37,7 +40,7 @@ Below are the keys that can be found in the [`legacy` DocSearch configs][14] and
|
|||
| `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] |
|
||||
| `page_rank` | [`pageRank`][31] | Can be added to the `recordProps` in [`helpers.docsearch`][30], should be passed as a **string** |
|
||||
| `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] |
|
||||
|
|
@ -62,13 +65,52 @@ 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've tried to make the migration as seamless as possible for you and took care of all the pain part:
|
||||
|
||||
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!
|
||||
- [Your existing config file][11] will be migrated to an [Algolia Crawler config][12]
|
||||
- Crawls will be started and scheduled
|
||||
- Your Algolia application will be ready to go with a populated index!
|
||||
|
||||
### What do I need to update to make the migration work?
|
||||
All you need to do is **update your frontend integration with the credentials you'll receive by email** like below:
|
||||
|
||||
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]!
|
||||
<Tabs
|
||||
groupId="language"
|
||||
defaultValue="js"
|
||||
values={[
|
||||
{ label: 'JavaScript', value: 'js', },
|
||||
{ label: 'React', value: 'react', }
|
||||
]
|
||||
}>
|
||||
<TabItem value="js">
|
||||
|
||||
```js app.js
|
||||
docsearch({
|
||||
container: '#docsearch',
|
||||
appId: 'YOUR_NEW_ALGOLIA_APP_ID',
|
||||
apiKey: 'YOUR_NEW_ALGOLIA_SEARCH_API_KEY',
|
||||
indexName: 'YOUR_INDEX_NAME', // it does not change
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="react">
|
||||
|
||||
```jsx App.js
|
||||
<DocSearch
|
||||
appId="YOUR_NEW_ALGOLIA_APP_ID"
|
||||
apiKey="YOUR_NEW_ALGOLIA_SEARCH_API_KEY"
|
||||
indexName="YOUR_INDEX_NAME" // it does not change
|
||||
/>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
### Why is the API key different in the dashboard?
|
||||
|
||||
Algolia apps come with a default search API key, which also allow you to list indices, settings and search on **every** indices of your app. In the email, we provide a search **ONLY** API key, scoped to your production index, so you don't have to worry disclosing it in the frontend.
|
||||
|
||||
### What should I do with my legacy config and credentials?
|
||||
|
||||
|
|
@ -51,7 +51,7 @@ recordExtractor: ({ helpers }) => {
|
|||
|
||||
### Using the Cheerio instance (`$`)
|
||||
|
||||
You can also use the provided [`Cheerio instance ($)`][14] to exclude content from the DOM:
|
||||
We provide a [`Cheerio instance ($)`][14] for you to retrieve or remove content from the DOM:
|
||||
|
||||
```js
|
||||
recordExtractor: ({ $, helpers }) => {
|
||||
|
|
@ -60,9 +60,7 @@ recordExtractor: ({ $, helpers }) => {
|
|||
|
||||
return helpers.docsearch({
|
||||
recordProps: {
|
||||
lvl0: {
|
||||
selectors: "header h1",
|
||||
},
|
||||
lvl0: "header h1",
|
||||
lvl1: "article h2",
|
||||
lvl2: "article h3",
|
||||
lvl3: "article h4",
|
||||
|
|
@ -74,9 +72,9 @@ recordExtractor: ({ $, helpers }) => {
|
|||
},
|
||||
```
|
||||
|
||||
### With fallback DOM selectors
|
||||
### Handling fallback DOM selectors
|
||||
|
||||
Each `lvlX` and `content` supports fallback selectors as an array of string, which allows for robust config files:
|
||||
Fallback selectors can be useful when retrieving content that might not exist in some pages:
|
||||
|
||||
```js
|
||||
recordExtractor: ({ $, helpers }) => {
|
||||
|
|
@ -103,10 +101,10 @@ recordExtractor: ({ $, helpers }) => {
|
|||
|
||||
### 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)_
|
||||
|
||||
Custom variables are added to your Algolia records to be used as filters in the frontend (e.g. `version`, `lang`, etc.):
|
||||
|
||||
```js
|
||||
recordExtractor: ({ helpers }) => {
|
||||
return helpers.docsearch({
|
||||
|
|
@ -150,7 +148,9 @@ 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:
|
||||
_Only the `lvl0` and [custom variables][13] selectors support this option_
|
||||
|
||||
You might want to structure your search results differently than your website, or provide a `defaultValue` to a potentially non-existent selector:
|
||||
|
||||
```js
|
||||
recordExtractor: ({ $, helpers }) => {
|
||||
|
|
@ -180,6 +180,34 @@ recordExtractor: ({ $, helpers }) => {
|
|||
},
|
||||
```
|
||||
|
||||
### Boosting search results with `pageRank`
|
||||
|
||||
_[`pageRank`](#pagerank) used to be an **integer**, it is now a **string**_
|
||||
|
||||
This parameter helps to boost records built from the current `pathsToMatch`. Pages with highest [`pageRank`](#pagerank) will be returned before pages with a lower [`pageRank`](#pagerank). Note that you can pass any numeric value **as a string**, including negative values:
|
||||
|
||||
```js
|
||||
{
|
||||
indexName: "YOUR_INDEX_NAME",
|
||||
pathsToMatch: ["https://YOUR_WEBSITE_URL/api/**"],
|
||||
recordExtractor: ({ $, helpers }) => {
|
||||
return helpers.docsearch({
|
||||
recordProps: {
|
||||
lvl0: "header h1",
|
||||
lvl1: "article h2",
|
||||
lvl2: "article h3",
|
||||
lvl3: "article h4",
|
||||
lvl4: "article h5",
|
||||
lvl5: "article h6",
|
||||
content: "article p, article li",
|
||||
pageRank: "30",
|
||||
},
|
||||
indexHeadings: true,
|
||||
});
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
## `recordProps` API Reference
|
||||
|
||||
### `lvl0`
|
||||
|
|
@ -205,6 +233,8 @@ type Lvl0 = {
|
|||
|
||||
> `type: string` | **optional**
|
||||
|
||||
See the [live example](#boosting-search-results-with-pagerank)
|
||||
|
||||
### Custom variables (`[k: string]`)
|
||||
|
||||
> `type: string | string[] | CustomVariable` | **optional**
|
||||
|
|
|
|||
|
|
@ -18,8 +18,8 @@
|
|||
"dependencies": {
|
||||
"@algolia/ui-library": "4.0.0-beta.71",
|
||||
"@docsearch/react": "3.0.0-alpha.41",
|
||||
"@docusaurus/core": "2.0.0-beta.6",
|
||||
"@docusaurus/preset-classic": "2.0.0-beta.6",
|
||||
"@docusaurus/core": "2.0.0-beta.8",
|
||||
"@docusaurus/preset-classic": "2.0.0-beta.8",
|
||||
"@mdx-js/react": "1.6.22",
|
||||
"@svgr/webpack": "5.5.0",
|
||||
"clsx": "1.1.1",
|
||||
|
|
|
|||
Loading…
Reference in a new issue