docs: clarify steps to add custom `lunr` index code (#1139)

docs/search.md

@@ -96,7 +96,7 @@ 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.
+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
@@ -128,19 +128,20 @@ 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.
+By default, the search feature indexes a page's `.content`, `.title`, and *some* headers within the `.content`. 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,9 +152,7 @@ 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`.
-Finally, append your custom fields on to the already existing `docs[i].content`.
+`_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
 const content_to_merge = [docs[i].content, docs[i].myusage, docs[i].myexamples];