update docs: Custom content for search index

docs/search.md

@@ -96,8 +96,8 @@ search.button: true
 
 ## Hiding pages from search
 
-Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page.
-To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
+Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g.,
+a 404 page. To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
 
 #### Example
 
@@ -129,18 +129,29 @@ Alternatively, you can create the file manually with [this content]({{ site.gith
 ## Custom content for search index
 
 By default, the search feature indexes a page's `.content`, `.title`, and *some* headers within the `.content`.
-Other data (ex front matter, files in `_data`, `assets`) is not indexed. To index additional data, users can customize what `lunr` indexes.
+Other data (e.g. front matter, files in `_data` and `assets`) is not indexed. Users can customize what is indexed.
 
 {: .warning }
 > Customizing search indices is an advanced feature that requires Javascript and Liquid knowledge.
 
-1. First, ensure that `assets/js/zzzz-search-data.json` is up-to-date; it can be regenerated with `rake` or manually (see:  ["Generate search index when used as a gem"](#generate-search-index-when-used-as-a-gem)).
-2. To add Liquid/Jekyll-based data: create a new include at the path `_includes/lunr/custom-data.json`. Insert custom Liquid code that reads various data (ex: `include.page`, `site.data`, `site.static_files`) that then generates valid [JSON](https://www.json.org/json-en.html) to add to the index.  Verify the fields in the generated `assets/js/search-data.json`.
-3. For all custom data (Liquid, JavaScript, or external): create a new include at the path `_includes/lunr/custom-index.js` to your site. Add valid JavaScript that creates relevant fields to add to the index. You may want to inspect `assets/js/just-the-docs.js` to better understand the code structure. **This is necessary to render any relevant custom index code.**
+1. When Just the Docs is a local or gem theme, ensure `assets/js/zzzz-search-data.json`
+   is up-to-date with [Generate search index when used as a gem](#generate-search-index-when-used-as-a-gem).
+2. Add a new file named `_includes/lunr/custom-data.json`. Insert custom Liquid code that reads
+   your data (e.g. the page object at `include.page`) then generates custom Javascript
+   fields that hold the custom data you want to index. Verify these fields in
+   the generated `assets/js/search-data.json`.
+3. Add a new file named `_includes/lunr/custom-index.js`. Insert custom Javascript
+   code that reads your custom Javascript fields and inserts them into the search index.
+   You may want to inspect `assets/js/just-the-docs.js` to better understand the code.
 
 #### Example
 
-`_includes/lunr/custom-data.json`: this example adds each page's `usage` and `examples` front matter fields, normalizes the text, and writes the text to custom Javascript `myusage` and `myexamples` fields.
+This example adds front matter `usage` and `examples` fields to the search index.
+
+`_includes/lunr/custom-data.json` custom code reads the page `usage` and `examples` fields,
+normalizes the text, and writes the text to custom Javascript `myusage` and `myexamples` fields.
+Javascript fields are similar yet [not the same as JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON#javascript_and_json_differences).
+`jsonify` will probably work for most scenarios.
 
 {% raw %}
 ```liquid
@@ -151,8 +162,8 @@ Other data (ex front matter, files in `_data`, `assets`) is not indexed. To inde
 ```
 {% endraw %}
 
-`_includes/lunr/custom-index.js` custom code is within a Javascript loop. All custom
-Javascript fields are accessed as fields of `docs[i]` such as `docs[i].myusage`.
+`_includes/lunr/custom-index.js` custom code is inserted into the Javascript loop of `assets/js/just-the-docs.js`.
+All custom Javascript fields are accessed as fields of `docs[i]` such as `docs[i].myusage`.
 Finally, append your custom fields on to the already existing `docs[i].content`.
 
 ```javascript