From ea2f81b2996b42fbff04e054a825da9c7c303cee Mon Sep 17 00:00:00 2001
From: Sarah Dayan <sarah.dayan@algolia.com>
Date: Thu, 4 Mar 2021 13:45:36 +0100
Subject: [PATCH] docs(createQuerySuggestionsPlugin): rewrite docs (#468)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs(createQuerySuggestionsPlugin): rewrite docs

* fix(createQuerySuggestionsPlugin): fix name

* fix: apply suggestions from code review

Co-authored-by: François Chalifour <francoischalifour@users.noreply.github.com>

* docs(createQuerySuggestionsPlugin): document new parameters

* fix: apply suggestions from code review

Co-authored-by: François Chalifour <francoischalifour@users.noreply.github.com>

* docs(createQuerySuggestionsPlugin): clarify description

Co-authored-by: François Chalifour <francoischalifour@users.noreply.github.com>
---
 .../docs/createQuerySuggestionsPlugin.md      | 89 ++++++++++++++++---
 1 file changed, 76 insertions(+), 13 deletions(-)

diff --git a/packages/website/docs/createQuerySuggestionsPlugin.md b/packages/website/docs/createQuerySuggestionsPlugin.md
index 254e4416e..fa709cf38 100644
--- a/packages/website/docs/createQuerySuggestionsPlugin.md
+++ b/packages/website/docs/createQuerySuggestionsPlugin.md
@@ -2,9 +2,35 @@
 id: createQuerySuggestionsPlugin
 ---
 
+The Query Suggestions plugin adds [Algolia Query Suggestions](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js/) to your autocomplete.
+
+## Installation
+
+First, you need to install the plugin.
+
+```bash
+yarn add @algolia/autocomplete-plugin-query-suggestions@alpha
+# or
+npm install @algolia/autocomplete-plugin-query-suggestions@alpha
+```
+
+Then import it in your project:
+
+```js
+import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
+```
+
+If you don't use a package manager, you can use a standalone endpoint:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-query-suggestions@alpha"></script>
+```
+
 ## Example
 
-```ts
+This example uses the plugin within [`autocomplete-js`](autocomplete-js), along with the [`algoliasearch`](https://www.npmjs.com/package/algoliasearch) API client.
+
+```js
 import algoliasearch from 'algoliasearch/lite';
 import { autocomplete } from '@algolia/autocomplete-js';
 import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
@@ -24,9 +50,9 @@ autocomplete({
 });
 ```
 
-With [Recent Searches](createLocalStorageRecentSearchesPlugin):
+You can combine this plugin with the [Recent Searches](createLocalStorageRecentSearchesPlugin) plugin to leverage the empty screen with recent and popular queries.
 
-```ts
+```js
 import algoliasearch from 'algoliasearch/lite';
 import { autocomplete } from '@algolia/autocomplete-js';
 import { createLocalStorageRecentSearchesPlugin } from '@algolia/autocomplete-plugin-recent-searches';
@@ -54,35 +80,39 @@ autocomplete({
 });
 ```
 
-## Import
+To see it in action, check [this demo on CodeSandbox](https://fzb4m.csb.app/).
 
-```ts
-import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
-```
-
-## Params
+## Parameters
 
 ### `searchClient`
 
 > `SearchClient` | required
 
+The initialized Algolia search client.
+
 ### `indexName`
 
 > `string` | required
 
+The index name.
+
 ### `getSearchParams`
 
-> [`() => SearchParameters`](https://www.algolia.com/doc/api-reference/search-api-parameters/)
+> `(params: { state: AutocompleteState }) => SearchParameters`
+
+A function returning [Algolia search parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/).
 
 ### `transformSource`
 
 > `(params: { source: AutocompleteSource, onTapAhead: () => void })`
 
-#### Example
+A function to transform the provided source.
+
+#### Examples
 
 Keeping the panel open on select:
 
-```tsx
+```jsx
 const querySuggestionsPlugin = createQuerySuggestionsPlugin({
   searchClient,
   indexName: 'instant_search_demo_query_suggestions',
@@ -99,7 +129,7 @@ const querySuggestionsPlugin = createQuerySuggestionsPlugin({
 
 Opening a link:
 
-```tsx
+```jsx
 const querySuggestionsPlugin = createQuerySuggestionsPlugin({
   searchClient,
   indexName: 'instant_search_demo_query_suggestions',
@@ -127,3 +157,36 @@ const querySuggestionsPlugin = createQuerySuggestionsPlugin({
   },
 });
 ```
+
+### `categoryAttribute`
+
+> `string | string[]`
+
+The attribute or attribute path to display categories for.
+
+#### Example
+
+```js
+const querySuggestionsPlugin = createQuerySuggestionsPlugin({
+  searchClient,
+  indexName: 'instant_search_demo_query_suggestions',
+  categoryAttribute: [
+    'instant_search',
+    'facets',
+    'exact_matches',
+    'hierarchicalCategories.lvl0',
+  ],
+});
+```
+
+### `categoriesLimit`
+
+> `number` | defaults to `1`
+
+How many items to display categories for.
+
+### `categoriesPerItem`
+
+> `number` | defaults to `1`
+
+The number of categories to display per item.