Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Highlight the word result that searched #2450

Open
LIGMATV opened this issue Jun 9, 2024 · 6 comments
Open

Highlight the word result that searched #2450

LIGMATV opened this issue Jun 9, 2024 · 6 comments
Milestone
Future

Comments

@LIGMATV
Copy link

LIGMATV commented Jun 9, 2024

Feature request

Problem or desire

I searching for the "Beginilah" result

Screenshot Capture - 2024-06-09 - 12-08-50

When i click the result, it just go to the Heading of text, not highlight the word.

Proposal

Highlight the word that searched, so we know where it is

Screenshot Capture - 2024-06-09 - 12-10-06

Implementation

Add new element for the highlited searched words like <mark class="searched"...
@Koooooo-7
Copy link
Member

Hi @LIGMATV , TBH, it is not that feasible to docsify since the search function (plugin) and the main contents are isolated.
It is unlike the search engine stuff that docsify does not do the global text search and highlights base on all the contents files before render it to HTML. In docsify, it is not correlative.
The search function works on its own INDEXs and when you click the search result to tell docsify where the anchor I want to go, it triggers main content to load.

@jhildenbiddle
Copy link
Member

I can think of a few different ways to handle this fairly easily.

Option 1: The search plugin can add a separate plugin to the plugins array that determines if a search is currently active and, if so, parses and marks content before it is rendered.

Option 2: When navigation occurs, the data-page attribute on the body is updated. Currently, this update occurs when a link is clicked and not when a page has loaded. If we change the behavior to update data-page after loading is complete, the search plugin could use a mutation observer on the <body> element, listening only for changes to this specific property. When a change is detected, the DOM can be walked and elements marked as needed.

The most challenging part will likely be determining which matches to mark and which ones to ignore. For example, we don't want mark matches within a <script>, <textarea>, <option>, comments, etc.

@jhildenbiddle jhildenbiddle added this to the 5.x milestone Jun 21, 2024
@Koooooo-7
Copy link
Member

Koooooo-7 commented Jun 24, 2024 •
edited
Loading

Hi @jhildenbiddle, I think highlight search content in main content is not that meaningful, it is not necessarily reasonable from a docs site perspective. So I don't think we need maintain this function on our side.

It is not a normal behavior for search engines or for a documentation site. The 'highlight' feature is used to display the matched contents in the search result list, not in the main content. This holds true even when using ElasticSearch or other search implementations in e-commerce search functionalities.

And back to the docs site functions itself:

  1. highlighting incomplete search results in the text can disrupt the reading experience.
  2. single search keyword is meaningless in a doc without any context, no user will try to search a single keyword and only focus on finding where the keyword is. Unless those uncommon cases:
    • The entire page is one long article without any sections, and you want to read the content starting with a particular unique keyword (because if the keyword is duplicated in the page, you need to switch the match results also).
    • The whole page/sites is a pure configurations docs without any other contents for the configurations list.

Additionally, the browser search function for the search matched target page is more convenient if really needs.

@Koooooo-7 Koooooo-7 modified the milestones: 5.x, Future Jun 24, 2024
@jhildenbiddle
Copy link
Member

jhildenbiddle commented Jun 24, 2024 •
edited
Loading

@Koooooo-7 --

I don't think there's a right or wrong answer on this one. It's a preference that can change based on the user, the type of search being performed, or where a matching search term is located in the content area.

My comment above was focused more on how we could implement highlighting matching search terms in the content area in response to the "it is not that feasible" statement in the comment prior to mine. Regarding if we should offer this feature, here are a few things to consider...

  • A quick review of Docsify competitors like Docusaurus, GitBook, Starlight, and VitePress shows that--to your point--none of them highlight matching search terms in the content area when a search is active. That said, we should consider these projects but not allow their features or limitations to dictate our own roadmap. Perhaps they do not offer this feature yet but will in the future, or perhaps they chose not to prioritize it because the third-party search tool they are using makes implementation more challenging (Starlight uses Pagefind, Docusaurus uses Algolia, VitePress uses minisearch, etc.). The point is that we shouldn't assume they made a conscience decision not to implement this feature unless we have reason to believe otherwise.
  • Like Docsify, all of the competitors above link to a heading rather than the matching search term in the content. There are pros and cons to this: the heading provides context for the matching search term it contains (pro), but the matching search term can be hard to find when it is part of a large block of content under a heading (con). The ability to quickly scan for a highlighted search term is, I believe, the primary reason why someone would want to highlight matching search terms in the content area.
  • The browser's built-in page search functionality can be used to find matching search terms in the content area, but it has issues: 1) it requires typing in the search term a second time and 2) the search begins at the top of the page and not the content area which means it will match all of the results in the sidebar before the content area.

highlighting incomplete search results in the text can disrupt the reading experience.

Not sure what you mean by "incomplete" search results. The behavior I am referring to is highlighting matching search results on pages loaded by clicking on a search result in a sidebar. When an active search term is modified, the previous search results are cleared as well as any highlighted content in the content area. We would not do "live" highlighting of the content area based on what a user types in our search field.

If users find content highlighting distracting, users can disable the feature (assuming a user-facing toggle is provided) or clear the search results via ESC or the clear button. The content and page position will remain unchanged when this occurs.

single search keyword is meaningless in a doc without any context

We cannot assume a heading is the only context needed/wanted for all matching search terms on every site. It is equally likely that the text surrounding a matching search term provides more useful context than the heading the search term resides under, in which case allowing users acquire this context as quickly as possible should be the goal. This is often true for matching search terms found in a large blocks of content, callouts/admonishments, list items, code blocks, etc.

Additionally, the browser search function for the search matched target page is more convenient if really needs.

See above.

My preference regarding this feature in order of preference:

  1. Provide a small "Highlight content" (or similar text) toggle below the search field when a search results is active. This allows site visitors to decide if they want matching content to be highlighted or not.
  2. Offer this as a search plugin option (e.g., highlightContent). This allows site maintainers to decide if they want matching content to be highlighted or not. Ideally, a user-facing toggle would still be displayed and setting this option would simply set the default state of the toggle so site visitors still retain control over this feature.
  3. Wait for someone else to implement this feature as a separate plugin which could.

Personally, I like option 1 with the toggle set to "off" by default.

@Koooooo-7
Copy link
Member

Koooooo-7 commented Jun 24, 2024 •
edited
Loading

@jhildenbiddle
I don't mean there is a right or wrong thing, but based on the product itself, the requirements have the priority based on the user experiences, project perspective, the functionality persona, and the conventions (don't mean something that we follow the competitors).

If the user requirements is not a common use case nor the common functions cross the competitors or other apps, and it is not a brand new things only we can do, I don't think we need bring it in with high priority.

A quick review of Docsify competitors like Docusaurus, GitBook, Starlight, and VitePress shows that--to your point--none of them highlight matching search terms in the content area when a search is active. That said, we should consider these projects but not allow their features or limitations to dictate our own roadmap. Perhaps they do not offer this feature yet but will in the future, or perhaps they chose not to prioritize it because the third-party search tool they are using makes implementation more challenging (Starlight uses Pagefind, Docusaurus uses Algolia, VitePress uses minisearch, etc.). The point is that we shouldn't assume they made a conscience decision not to implement this feature unless we have reason to believe otherwise.

I'm not a follower that we only do others do, but again, I consider about the product itself.
Besides, the google, wiki, and other normal websites/apps, they don‘t have this functions either.
Although they implement the search functions all by themselves with ElasticSearch I mentioned or other advanced search solutions.
I suppose some of them consider the performances on highlighting whole page.

I participated design and know few （3? IIUC） of sites do have the contents highlight functions as an advanced search function also.
(They have a label/button on the page top (such as Highlighting keyword "XXX") as a toggle to disable the highlight like your idea.) And they are almost some more complex mixed media type tools site.

We cannot assume a heading is the only context needed/wanted for all matching search terms on every site.

Yes, but it brings the thing what we normally need:
This contents blowing this heading is related to the search things.

It is equally likely that the text surrounding a matching search term provides more useful context than the heading the search term resides under, in which case allowing users acquire this context as quickly as possible should be the goal.

Yes, I agree, and this is what makes this requirement reasonable.

This is often true for matching search terms found in a large blocks of content, callouts/admonishments, list items, code blocks, etc.

For a short page/section, the highlight or not doesn't matter.

For a long content, such as highlight a function name foo inside a 5000 lines code block. It only useful when the search content is unique as I said. Otherwise, the searched keyword has duplicated in the target page/ code block.
What should user do?

  • Click another search matched keyword result (maybe wrong again since the search result box brings limited context, unlike the SEO stuff brings to the spider). Thats fine.
  • Use the browser search to fast jump to next keyword place. (If the highlight keywords function can not brings this function, the highlight is also meaningless)

Personally, normally, I don't think user will scroll down to find the highlight part in the 5000 lines code block.

highlighting incomplete search results in the text can disrupt the reading experience.

highlighting incomplete search means I input the docum (entation), then I click the search target page, it highlight this docum is also annoying. ( Although we can say that this highlighted area is a sign.)
It makes the search result has higher rate to duplicated also.

I believe that we can make it.

Option1 is great to me.

Below the search input box, a grey highlight on main content [toggle].

I only consider should we brings it to our side as a common feature very quick.
If some implement it as a plugin or they customize docsify by themselves is fine to me.
So, it is a low priority requirements to me. If more and more users urge to this, we could consider again and put it on the table or we have sufficient time on this. Thats y I moved it to Future.

BTW: the search plugin's priority higher things in my mind:

  1. move out as an individual one. (project reorg)
  2. storage layer change. ( cos it is no other choices, unlike the search highlight has the browser helper)

@jhildenbiddle
Copy link
Member

jhildenbiddle commented Jun 24, 2024 •
edited
Loading

Agreed on the priority. This doesn't need to be part of v5 release, but it could be handled in a v5.x point release in the future. I'm fine leaving I tagged as "Future" for now.

Regarding search plugin priorities, I would add #1369 to the list of items we should get to sooner than later.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
Future
Development

No branches or pull requests
3 participants
@jhildenbiddle @Koooooo-7 @LIGMATV