From f97a0fbeb5bd9da9838edf1112616e937fb4c33c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Chalifour?= <francois.chalifour@gmail.com>
Date: Wed, 9 Sep 2020 14:59:37 +0200
Subject: [PATCH] docs(js): document highlighting utils

---
 packages/website/docs/highlightItem.md        | 51 +++++++++++++++++++
 packages/website/docs/reverseHighlightItem.md | 51 +++++++++++++++++++
 packages/website/docs/reverseSnippetItem.md   | 51 +++++++++++++++++++
 packages/website/docs/snippetItem.md          | 51 +++++++++++++++++++
 packages/website/sidebars.js                  | 10 +++-
 5 files changed, 213 insertions(+), 1 deletion(-)
 create mode 100644 packages/website/docs/highlightItem.md
 create mode 100644 packages/website/docs/reverseHighlightItem.md
 create mode 100644 packages/website/docs/reverseSnippetItem.md
 create mode 100644 packages/website/docs/snippetItem.md

diff --git a/packages/website/docs/highlightItem.md b/packages/website/docs/highlightItem.md
new file mode 100644
index 000000000..cedecf371
--- /dev/null
+++ b/packages/website/docs/highlightItem.md
@@ -0,0 +1,51 @@
+---
+id: highlightItem
+---
+
+Returns a string with highlighted and escaped matching parts of an Algolia hit.
+
+# Example
+
+```js
+import { highlightItem } from '@algolia/autocomplete-js';
+
+const item = {}; // fetch an Algolia hit
+const highlightedValue = highlightItem({
+  item,
+  attribute: 'query',
+});
+```
+
+# Reference
+
+## Params
+
+### `item`
+
+> `AlgoliaHit` | required
+
+The Algolia hit to retrieve the attribute value from.
+
+### `attribute`
+
+> `string` | required
+
+The attribute to retrieve the highlight value from.
+
+### `highlightPreTag`
+
+> `string` | defaults to `<mark>`
+
+The HTML tag to prefix the value with.
+
+### `highlightPostTag`
+
+> `string` | defaults to `</mark>`
+
+The HTML tag to suffix the value with.
+
+### `ignoreEscape`
+
+> `string[]` | defaults to `[]`
+
+The characters to skip from escaping.
diff --git a/packages/website/docs/reverseHighlightItem.md b/packages/website/docs/reverseHighlightItem.md
new file mode 100644
index 000000000..59ad81d8b
--- /dev/null
+++ b/packages/website/docs/reverseHighlightItem.md
@@ -0,0 +1,51 @@
+---
+id: reverseHighlightItem
+---
+
+Returns a string with highlighted and escaped non-matching parts of an Algolia hit.
+
+# Example
+
+```js
+import { reverseHighlightItem } from '@algolia/autocomplete-js';
+
+const item = {}; // fetch an Algolia hit
+const highlightedValue = reverseHighlightItem({
+  item,
+  attribute: 'query',
+});
+```
+
+# Reference
+
+## Params
+
+### `item`
+
+> `AlgoliaHit` | required
+
+The Algolia hit to retrieve the attribute value from.
+
+### `attribute`
+
+> `string` | required
+
+The attribute to retrieve the highlight value from.
+
+### `highlightPreTag`
+
+> `string` | defaults to `<mark>`
+
+The HTML tag to prefix the value with.
+
+### `highlightPostTag`
+
+> `string` | defaults to `</mark>`
+
+The HTML tag to suffix the value with.
+
+### `ignoreEscape`
+
+> `string[]` | defaults to `[]`
+
+The characters to skip from escaping.
diff --git a/packages/website/docs/reverseSnippetItem.md b/packages/website/docs/reverseSnippetItem.md
new file mode 100644
index 000000000..0a7bd5c6c
--- /dev/null
+++ b/packages/website/docs/reverseSnippetItem.md
@@ -0,0 +1,51 @@
+---
+id: reverseSnippetItem
+---
+
+Returns a string with highlighted and escaped non-matching parts of an Algolia hit snippet.
+
+# Example
+
+```js
+import { reverseSnippetItem } from '@algolia/autocomplete-js';
+
+const item = {}; // fetch an Algolia hit
+const reverseSnippetedValue = reverseSnippetItem({
+  item,
+  attribute: 'query',
+});
+```
+
+# Reference
+
+## Params
+
+### `item`
+
+> `AlgoliaHit` | required
+
+The Algolia hit to retrieve the attribute value from.
+
+### `attribute`
+
+> `string` | required
+
+The attribute to retrieve the snippet value from.
+
+### `highlightPreTag`
+
+> `string` | defaults to `<mark>`
+
+The HTML tag to prefix the value with.
+
+### `highlightPostTag`
+
+> `string` | defaults to `</mark>`
+
+The HTML tag to suffix the value with.
+
+### `ignoreEscape`
+
+> `string[]` | defaults to `[]`
+
+The characters to skip from escaping.
diff --git a/packages/website/docs/snippetItem.md b/packages/website/docs/snippetItem.md
new file mode 100644
index 000000000..79cee16cf
--- /dev/null
+++ b/packages/website/docs/snippetItem.md
@@ -0,0 +1,51 @@
+---
+id: snippetItem
+---
+
+Returns a string with highlighted and escaped matching parts of an Algolia hit snippet.
+
+# Example
+
+```js
+import { snippetItem } from '@algolia/autocomplete-js';
+
+const item = {}; // fetch an Algolia hit
+const snippetedValue = snippetItem({
+  item,
+  attribute: 'query',
+});
+```
+
+# Reference
+
+## Params
+
+### `item`
+
+> `AlgoliaHit` | required
+
+The Algolia hit to retrieve the attribute value from.
+
+### `attribute`
+
+> `string` | required
+
+The attribute to retrieve the snippet value from.
+
+### `highlightPreTag`
+
+> `string` | defaults to `<mark>`
+
+The HTML tag to prefix the value with.
+
+### `highlightPostTag`
+
+> `string` | defaults to `</mark>`
+
+The HTML tag to suffix the value with.
+
+### `ignoreEscape`
+
+> `string[]` | defaults to `[]`
+
+The characters to skip from escaping.
diff --git a/packages/website/sidebars.js b/packages/website/sidebars.js
index 6a33d024c..aa653c9a8 100644
--- a/packages/website/sidebars.js
+++ b/packages/website/sidebars.js
@@ -23,7 +23,15 @@ module.exports = {
       {
         type: 'category',
         label: 'autocomplete-js',
-        items: ['autocomplete-js', 'getAlgoliaHits-js', 'getAlgoliaResults-js'],
+        items: [
+          'autocomplete-js',
+          'getAlgoliaHits-js',
+          'getAlgoliaResults-js',
+          'highlightItem',
+          'reverseHighlightItem',
+          'snippetItem',
+          'reverseSnippetItem',
+        ],
       },
       {
         type: 'category',