fix(docs-search): restore fragment navigation and improve fuzzy search

[satyansh2004]

Related Issue

Fixes #2362

Summary

Improves the documentation search system by adding fuzzy search while preserving Puter's existing text-fragment navigation.

The goal is to make the docs search more tolerant to typos and similar terms while still allowing users to jump directly to the relevant content in the page.

Changes

• Added fuzzy search support to improve matching for similar words and small typos
• Restored and preserved text fragment navigation using #:~:text= so the browser highlights the matched text
• Improved search ranking so exact phrase matches appear before weaker matches
• Cleaned search result snippets to remove metadata such as title: and description:
• Fixed highlighting so full matched words are highlighted instead of individual characters
• Maintained prefix/suffix fragment logic to correctly handle duplicate text occurrences
• Ensured results still navigate to the nearest relevant section when an exact fragment cannot be generated

Testing

Tested locally using the docs development server and compared behavior with the live documentation.

Queries tested:

• hosting infrastructure
• host infrastructure
• host infrastucture
• key value
• create hosting

Verified that:

• exact matches rank correctly
• fuzzy search returns relevant results
• search snippets display clean text
• matched words are highlighted correctly
• clicking a result navigates to the correct page and highlights the text fragment
• navigation scrolls to the appropriate section

Notes

This change improves the overall search experience without altering the existing documentation structure or navigation system.

[reynaldichernando]

hi @satyansh2004 , thanks for the PR, checking

[satyansh2004]

Thanks for taking a look!

Please let me know if you'd like me to adjust anything or add more tests. Happy to make any changes needed.

[reynaldichernando]

hi @satyansh2004 thank you for the PR, i have tested it, and here’s some comments

requirements based on the issue:

• supports fuzzy search ✅
• still maintain our text fragment matching ✅
• if it's not an exact match (fuzzy) we still want the search result to jump somewhere, and the way it's done is to jump to the nearest subheading ❌

notes:

• for exact match, it auto highlights the entire word, while not in the requirement, i’m fine with this 👍
• because the way we do text fragment matching we also need the full word, so what’s shown here is consistent with what we match with text fragment
• for fuzzy match, it also highlights what it thinks is close match, i’m fine with this 👍
• i don’t think the fuzzy match jump to nearest subheading works yet, right now it opens the page without any matched subheading
• why do we still use the old search index and not fuse native search index?

in summary i think this PR is halfway there, its just some things are not complete yet

an idea i have for the search index (doesn’t have to follow this exactly) is to index each sections (just divided per H2 is okay) instead of the entire page

index structure:

• title (existing, the page title)
• path (existing, the page path)
• subheading (new, the subheading id attribute, that we can use for the jump)
• subheadingTitle (new, the subheading text itself, for showing in the search result)
• text (existing, but instead of containing the whole file, its just per section)

more detail on the text: it should only contain the text up until the next subheading, then its considered a new document
(h1 to the next h2 is a section, first h2 to the second h2 is a section, and so on)

to form the final fuzzy match url we can simply do #

feel free to clarify if anything’s unclear 🙏

[satyansh2004]

Thanks for the detailed review!
I'll update the search indexing structure and improve the fuzzy navigation behavior based on your suggestions.

[satyansh2004]

I've pushed the requested changes. The search index now chunks by H2 sections and fuzzy navigation jumps to the closest subheading while keeping existing fuzzy search and fragment matching behavior intact. Happy to adjust further if needed.

[reynaldichernando]

hi @satyansh2004, thank you for the changes, i have reviewed and tested it, so far here are some of my comments:

• the subheading jump works great, if you search “ship cloud” it should jump to “Everybody wins!” subheading
• we are somehow still using the old index.json, since you used Fuse, they also have their own search index https://www.fusejs.io/api/indexing.html
  • you can replace our old index with fuse’s index, and load this instead of using the old index.json
• a minor UX suggestion i have, is to have the subheading visible in the autocomplete, something like <title> >
  • User-Pays Model > Everybody wins!
  • and the description to highlight the matched phrase
  • 
  • this is what it looks like now, the subheading is inside the text and description highlights the entire text
  • although i'm not too sure about the highlighting part, let me know if you have some insights as to how fuse determine this

[satyansh2004]

Thanks for the feedback!

I'll update the implementation to use Fuse's index and add matched text highlighting in the autocomplete results.

Will push the changes shortly.

[satyansh2004]

Thanks for the suggestions! I've pushed an update that switches to Fuse's index and improves the highlighting of matched text in the search results. Everything else should behave the same as before.

Happy to tweak anything further if needed.

[satyansh2004]

Thanks for the feedback! I’ve updated the implementation to generate the Fuse index at build time using Fuse.createIndex and serialize it to index.json. On the client side, search.js now loads the index and reconstructs it using Fuse.parseIndex.

Search behavior should remain unchanged. Let me know if you'd like any adjustments.