docs(parseAlgoliaHitSnippet): rewrite guides (#480)

* docs(autocomplete-preset-algolia): add common note

* docs(parseAlgoliaHitSnippet): rewrite guides

* docs(parseAlgoliaHitSnippet): fix examples

* docs(parseAlgoliaHitSnippet): add descriptions

* docs(parseAlgoliaHitSnippet): fix text

* fix: apply suggestions from code review

Co-authored-by: François Chalifour <[email protected]>

Co-authored-by: François Chalifour <[email protected]>

Author: sarahdayan

packages/website/docs/parseAlgoliaHitSnippet.md

@@ -2,14 +2,44 @@
 id: parseAlgoliaHitSnippet
 ---
 
-Returns the snippeted parts of an Algolia hit.
+import PresetAlgoliaNote from './partials/preset-algolia/note.md'
 
-## Example with a single string
+Returns the highlighted parts of an Algolia hit's snippet.
+
+The `parseAlgoliaHitSnippet` function lets you parse the highlighted parts of an Algolia hit's snippet.
+
+<PresetAlgoliaNote />
+
+## Installation
+
+First, you need to install the preset.
+
+```bash
+yarn add @algolia/autocomplete-preset-algolia@alpha
+# or
+npm install @algolia/autocomplete-preset-algolia@alpha
+```
+
+Then import it in your project:
 
 ```js
 import { parseAlgoliaHitSnippet } from '@algolia/autocomplete-preset-algolia';
+```
 
-// Fetch an Algolia hit
+If you don't use a package manager, you can use a standalone endpoint:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-preset-algolia@alpha"></script>
+```
+
+## Examples
+
+### With a single string
+
+```js
+import { parseAlgoliaHitSnippet } from '@algolia/autocomplete-preset-algolia';
+
+// An Algolia hit for query "lap"
 const hit = {
   name: 'Laptop',
   _snippetResult: {
@@ -18,20 +48,20 @@ const hit = {
     },
   },
 };
-const snippetParts = parseAlgoliaHitSnippet({
+const snippetedParts = parseAlgoliaHitSnippet({
   hit,
   attribute: 'name',
 });
 
-// => [{ value: 'Lap', isHighlighted: true }, { value: 'top', isHighlighted: false }]
+// [{ value: 'Lap', isHighlighted: true }, { value: 'top', isHighlighted: false }]
 ```
 
-## Example with nested attributes
+### With nested attributes
 
 ```js
 import { parseAlgoliaHitSnippet } from '@algolia/autocomplete-preset-algolia';
 
-// Fetch an Algolia hit
+// An Algolia hit for query "lap"
 const hit = {
   name: {
     type: 'Laptop',
@@ -44,24 +74,30 @@ const hit = {
     },
   },
 };
-const snippetParts = parseAlgoliaHitSnippet({
+const snippetedParts = parseAlgoliaHitSnippet({
   hit,
   attribute: ['name', 'type'],
 });
 
-// => [{ value: 'Lap', isHighlighted: true }, { value: 'top', isHighlighted: false }]
+// [{ value: 'Lap', isHighlighted: true }, { value: 'top', isHighlighted: false }]
 ```
 
-## Params
+## Parameters
 
 ### `hit`
 
 > `AlgoliaHit` | required
 
-The Algolia hit to retrieve the attribute value from.
+The Algolia hit whose attribute to retrieve the snippet from.
 
 ### `attribute`
 
 > `string | string[]` | required
 
-The attribute to retrieve the snippet value from. You can use the array syntax to reference the nested attributes.
+The attribute to retrieve the snippet from. You can use the array syntax to reference nested attributes.
+
+## Returns
+
+> `ParsedAttribute[]`
+
+An array of the parsed attribute's parts.

packages/website/docs/snippetHit.md

@@ -2,42 +2,84 @@
 id: snippetHit
 ---
 
-Returns a virtual node with matching parts of an Algolia hit snippet.
+Returns virtual nodes with highlighted matching parts of an Algolia hit's snippet.
 
-## Example
+The `snippetHit` function lets you turn an Algolia hit's snippet into a virtual node with highlighted matching parts for a given attribute.
+
+## Examples
+
+### With a single string
+
+To determine what attribute to parse, you can pass it as a string.
 
 ```js
 import { snippetHit } from '@algolia/autocomplete-js';
 
-const hit = {}; // fetch an Algolia hit
+// An Algolia hit for query "he"
+const hit = {
+  query: 'Hello there',
+  _snippetResult: {
+    query: {
+      value:
+        '__aa-highlight__He__/aa-highlight__llo t__aa-highlight__he__/aa-highlight__re',
+    },
+  },
+};
 const snippetedValue = snippetHit({
   hit,
   attribute: 'query',
 });
 ```
 
-## Params
+### With nested attributes
 
-### `hit`
+If you're referencing a nested attribute, you can use the array syntax.
 
-> `AlgoliaHit` | required
+```js
+import { snippetHit } from '@algolia/autocomplete-js';
 
-The Algolia hit to retrieve the attribute value from.
+// An Algolia hit for query "he"
+const hit = {
+  query: {
+    title: 'Hello there',
+  }
+  _snippetResult: {
+    query: {
+      title: {
+        value:
+          '__aa-highlight__He__/aa-highlight__llo t__aa-highlight__he__/aa-highlight__re',
+      },
+    },
+  },
+};
+const snippetedValue = snippetHit({
+  hit,
+  attribute: ['query', 'title'],
+});
+```
 
-### `attribute`
+## Parameters
 
-> `string` | required
+### `hit`
 
-The attribute to retrieve the snippet value from.
+> `AlgoliaHit` | required
 
-### `highlightPreTag`
+The Algolia hit whose attribute to retrieve the snippet from.
 
-> `string` | defaults to `<mark>`
+### `attribute`
 
-The HTML tag to prefix the value with.
+> `string | string[]` | required
+
+The attribute to retrieve the snippet from. You can use the array syntax to reference nested attributes.
 
 ### `tagName`
 
 > `string` | defaults to `mark`
 
 The tag name of the virtual node.
+
+## Returns
+
+> `HighlightItemParams<THit>`
+
+Virtual nodes with the snippet.