Gitversion: How to search on the new docs page?

[afcruzs]

I haven't been able to find a free-text search field on the new docs. Looks like Wyam supports it: https://wyam.io/modules/searchindex, can we enable this on the docs?

It's really hard having to navigate through each section of the docs without search. Hopefully I am just not able to see where the search button is :)

Edit: you can search but only the "API" section, _not in the docs section_

[arturcic]

@gep13

[gep13]

@arturcic @afcruzs I _believe_ that this is possible, but I will need to check up on a couple things. Leave this with me, and I will find out.

[daveaglick]

👋 maintainer of Wyam here! First, a little background...

There are essentially two ways a static site can enable search functionality:

• Through a client-side library like Lunr.js.
• Through an API or service like Algolia.

Each approach has some limitations. Client-side searching means that the entire index has to be downloaded by the client and the search engine needs to perform all the indexing _at runtime_. That can be very, very expensive for big indexes and lots of content. On the other hand, server-side searching is more difficult mechanically to set up and use because you have to make sure the index is being updated on every change.

In both cases, a search index must be generated that tells the engine (whether it lives in the client browser or out in the cloud somewhere) what can be searched. That's where the Wyam SearchIndex module comes in - it knows how to create the right kind of JSON file that Lunr.js (a client-side search engine in JavaScript) can read. However, due to the limitations of client-side search Wyam doesn't use it for documentation content because the experience gets bad fast with a lot of docs pages. The client essentially has to download _every_ page to populate the index. It's best for constrained indexes without free text like API searching where you only have a handful of symbol names to search through (which is why Wyam _does_ support API searching out of the box).

So @gep13 has a couple options here:

• Add an extra pipeline in the Wyam config file for the GitVersion docs that uses the SearchIndex module to generate a search index for the content of the Pages pipeline. The Lunr.js client-side JS code would also need to be added to the layout and read the generated index.
• Somehow get the content of the pages and send it to Algolia (or Azure Search, etc.) out-of-band during the build process then add an API call to the search service in the layout. I've done this in the past by adding an extra pipeline that reads the content of documents from the Pages pipeline and writes it to a big XML file outside the normal "output" folder. Then I have Cake read that XML file and talk to Algolia during the build to update the index. This is how Discover .NET did it up until recently.

Hopefully that made sense. @gep13 let me know if this is something you want to pursue. Just FYI it'll be much easier (like most things) in Statiq since that'll have built-in deployment and Algolia support, but we're still months away from an out-of-the-box Statiq docs capability.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. After 30 days from now, it will be closed if no further activity occurs. Thank you for your contributions.