Possible documentation improvement around highlighting and components

[rcuhljr]

Would it make sense to add to the documentation around Templates and Components (specifically the highlight ones) that they won't work to highlight the default results from queries to Algolia? Algolia indexes return highlight results using <em> tags by default, however the Highlight component will not work with any results not using the HIGHLIGHT_PRE_TAG and HIGHLIGHT_POST_TAG source.

I found this fairly unintuitive and only eventually found any mention of them in documentation in the GetAlgoliaResults helper which is described as a utility to query multiple indices at once, I did not use it because I'm only working with one index and it didn't seem obvious that it would contain the underlying search parameters that are required for highlighting to function. Even had I found them here they are simply listed as default search parameters and no importance is placed upon them.

[dhayab]

Hi, thanks for your feedback. The highlighting and snippeting components are indeed designed to work in conjunction with getAlgoliaResults(). Rendering Algolia results retrieved by any other mean will require the added search parameters you've discovered.

We'll add a clarification in the templating section.

[sarahdayan]

Hey @rcuhljr, and thanks for raising this point.

We indeed don't document this specificity of the highlighting components, because our goal is to provide all the building blocks for you to create your autocomplete experience without having to care about search-related implementation detail.

We expect anyone who needs to search into one or multiple Algolia indices to use getAlgoliaResults. It doesn't only work out of the box with the highlighting components, it also takes care of batching requests across sources and plugins to minimize search requests.

As you mentioned, the problem as it appears to me is that we didn't well explained that getAlgoliaResults applies to querying as single index as well. Ultimately, I don't believe we should reveal implementation details of the highlighting components, but better promote usage of getAlgoliaResults. Would you agree?

[sarahdayan]

I've updated the docs as suggested in my above message, this should be live soon.

[rcuhljr]

That's a fair assessment. I think the new documentation makes it clear that it is less of an optional component.