Updated site search documentation

Author: squidfunk

docs/insiders.md

@@ -32,8 +32,8 @@ tied to it are merged back into Material for MkDocs and released for general
 availability. Bugfixes will always be released simultaneously in both editions.
 
 See the [roadmap][4] for a list of already available and upcoming features, and
-for demonstration purposes, [the official docs][5] built with Material for
-MkDocs Insiders.
+for demonstration purposes, [the official documentation][5] built with Material
+for MkDocs Insiders.
 
   [4]: #roadmap
   [5]: https://squidfunk.github.io/mkdocs-material-insiders/
@@ -75,7 +75,7 @@ in Material for MkDocs Insiders.
 ### Madame Jeanette
 
 [:octicons-fire-24: Funding goal: __$500__][6] ·
-:octicons-lock-24: Status: _exclusively available_
+:octicons-lock-24: Status: _exclusive_
 
 New features and improvements for _search_, including:
 
@@ -88,11 +88,11 @@ New features and improvements for _search_, including:
 ### Prairie Fire
 
 [:octicons-fire-24: Funding goal: __$1,000__][6] ·
-:octicons-lock-24: Status: _pending_
+:octicons-lock-24: Status: _exclusive_
 
 New features and improvements for _content and toc_, including:
 
-- [ ] Highlighting of matched search terms in content area
+- [x] Highlighting of matched search terms in content area
 - [ ] Better support for wide screens, i.e. more horizontal space
 - [ ] Table of contents can be moved into navigation for more space
 - [ ] Table of contents shows which sections have search results

docs/setup/setting-up-site-search.md

@@ -17,10 +17,10 @@ made available [offline][1].
 
 [:octicons-file-code-24: Source][2] ·
 [:octicons-cpu-24: Plugin][3] ·
-[:octicons-heart-fill-24:{: .tx-heart } Insiders: new search UI/UX](../insiders.md){: .tx-insiders }
+[:octicons-heart-fill-24:{: .tx-heart } Insiders – improved user experience][4]{: .tx-insiders }
 
 The [built-in search plugin][3] integrates seamlessly with Material for MkDocs,
-adding multilingual client-side search with [lunr][4] and [lunr-languages][5].
+adding multilingual client-side search with [lunr][5] and [lunr-languages][6].
 It's enabled by default, but must be re-added to `mkdocs.yml` when other plugins
 are used:
 
@@ -34,9 +34,9 @@ The following options are supported:
 `lang`{: #lang }
 
 :   :octicons-milestone-24: Default: _automatically set_ – This option allows
-    to include the language-specific stemmers provided by [lunr-languages][5].
+    to include the language-specific stemmers provided by [lunr-languages][6].
     Note that Material for MkDocs will set this automatically based on the
-    [site language][6], but it may be overridden, e.g. to support multiple
+    [site language][7], but it may be overridden, e.g. to support multiple
     languages:
 
     === "A single language"
@@ -106,7 +106,7 @@ The following options are supported:
 `prebuild_index`{: #prebuild-index }
 
 :   :octicons-milestone-24: Default: `false` · :octicons-beaker-24:
-    Experimental – MkDocs can generate a [prebuilt index][7] of all pages during
+    Experimental – MkDocs can generate a [prebuilt index][8] of all pages during
     build time, which provides performance improvements at the cost of more
     bandwidth, as it reduces the build time of the search index:
 
@@ -126,50 +126,55 @@ them at your own risk._
 
   [2]: https://github.com/squidfunk/mkdocs-material/tree/master/src/assets/javascripts/integrations/search
   [3]: https://www.mkdocs.org/user-guide/configuration/#search
-  [4]: https://lunrjs.com
-  [5]: https://github.com/MihaiValentin/lunr-languages
-  [6]: changing-the-language.md#site-language
-  [7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
+  [4]: ../insiders.md
+  [5]: https://lunrjs.com
+  [6]: https://github.com/MihaiValentin/lunr-languages
+  [7]: changing-the-language.md#site-language
+  [8]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
 
 ### Highlighting search
 
-[:octicons-file-code-24: Source][2] ·
+[:octicons-file-code-24: Source][4] ·
 :octicons-unlock-24: Feature flag ·
 :octicons-beaker-24: Experimental ·
-[:octicons-heart-fill-24:{: .tx-heart } Insiders](../insiders.md){: .tx-insiders }
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][4]{: .tx-insiders }
 
-When `search.highlighting` is activated and a user clicks on a search result,
-Material for MkDocs will highlight all occurrences. It can be enabled via
-`mkdocs.yml` with:
+When _search highlighting_ is activated and a user clicks on a search result,
+Material for MkDocs will highlight all occurrences after following the link.
+It can be enabled via `mkdocs.yml` with:
 
 ``` yaml
 theme:
   features:
     - search.highlight
 ```
 
-When searching for `"code blocks"`, the resulting page will look like:
+Searching for `"code blocks"` yields:
+
+[![Search highlighting][9]][9]
 
-![Search highlighting][8]
+_Give this feature a try on [the official documentation][10] built with Material
+for MkDocs Insiders!_
 
-  [8]: ../assets/search-highlighting.png
+  [9]: ../assets/search-highlighting.png
+  [10]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks
 
 ### Offline search
 
-[:octicons-file-code-24: Source][9] ·
-[:octicons-cpu-24: Plugin][10] · :octicons-beaker-24: Experimental
+[:octicons-file-code-24: Source][11] ·
+[:octicons-cpu-24: Plugin][12] · :octicons-beaker-24: Experimental
 
 If you distribute your documentation as `*.html` files, the built-in search
 will not work out-of-the-box due to the restrictions modern browsers impose for
-security reasons. This can be mitigated with the [localsearch][10] plugin in
-combination with @squidfunk's [iframe-worker][11] polyfill.
+security reasons. This can be mitigated with the [localsearch][12] plugin in
+combination with @squidfunk's [iframe-worker][13] polyfill.
 
-For setup instructions, refer to the [official documentation][12].
+For setup instructions, refer to the [official documentation][14].
 
-  [9]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390
-  [10]: https://github.com/wilhelmer/mkdocs-localsearch/
-  [11]: https://github.com/squidfunk/iframe-worker
-  [12]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
+  [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390
+  [12]: https://github.com/wilhelmer/mkdocs-localsearch/
+  [13]: https://github.com/squidfunk/iframe-worker
+  [14]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
 
 ## Customization
 
@@ -183,12 +188,12 @@ your needs.
 
 ### Query transformation
 
-[:octicons-file-code-24: Source][13] ·
+[:octicons-file-code-24: Source][15] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
 When a user enters a query into the search box, the query is pre-processed
 before it is submitted to the search index. Material for MkDocs will apply the
-following transformations, which can be customized by [extending the theme][14]:
+following transformations, which can be customized by [extending the theme][16]:
 
 ``` ts
 /**
@@ -213,12 +218,12 @@ following transformations, which can be customized by [extending the theme][14]:
  *    asterisk (wildcard) in between terms, which can be denoted by whitespace,
  *    any non-control character, or a word boundary.
  *
- * @param value - Query value
+ * @param query - Query value
  *
  * @return Transformed query value
  */
-function defaultTransform(value: string): string {
-  return value
+function defaultTransform(query: string): string {
+  return query
     .split(/"([^"]+)"/g)                            /* => 1 */
       .map((terms, i) => i & 1
         ? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +")
@@ -234,7 +239,7 @@ function defaultTransform(value: string): string {
 If you want to switch to the default behavior of the `mkdocs` or `readthedocs`
 template, both of which don't transform the query prior to submission, or
 customize the `transform` function, you can do this by [overriding the 
-`config` block][15]:
+`config` block][17]:
 
 ``` html
 {% block config %}
@@ -251,19 +256,19 @@ customize the `transform` function, you can do this by [overriding the
 The `transform` function will receive the query string as entered by the user
 and must return the processed query string to be submitted to the search index.
 
-  [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
-  [14]: ../customization.md#extending-the-theme
-  [15]: ../customization.md#overriding-blocks
+  [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
+  [16]: ../customization.md#extending-the-theme
+  [17]: ../customization.md#overriding-blocks
 
 ### Custom search
 
-[:octicons-file-code-24: Source][16] ·
+[:octicons-file-code-24: Source][18] ·
 :octicons-mortar-board-24: Difficulty: _challenging_
 
-Material for MkDocs implements search as part of a [web worker][17]. If you
+Material for MkDocs implements search as part of a [web worker][19]. If you
 want to switch the web worker with your own implementation, e.g. to submit
 search to an external service, you can add a custom JavaScript file to the `docs`
-directory and [override the `config` block][15]:
+directory and [override the `config` block][17]:
 
 ``` html
 {% block config %}
@@ -280,8 +285,8 @@ message format using _discriminated unions_, i.e. through the `type` property
 of the message. See the following interface definitions to learn about the
 message formats:
 
-* [:octicons-file-code-24: `SearchMessage`][18]
-* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][19]
+* [:octicons-file-code-24: `SearchMessage`][20]
+* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][21]
 
 The sequence and direction of messages is rather intuitive:
 
@@ -290,7 +295,7 @@ The sequence and direction of messages is rather intuitive:
 * :octicons-arrow-right-24: `SearchQueryMessage`
 * :octicons-arrow-left-24: `SearchResultMessage`
 
-  [16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
-  [17]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
-  [18]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
-  [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts
+  [18]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
+  [19]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
+  [20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
+  [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts