Making WordPress.org

Opened 8 weeks ago

#7530 new enhancement

More relevant block editor handbook search

Reported by: gaambo's profile gaambo Owned by:
Milestone: Priority: normal
Component: Developer Hub Keywords:
Cc:

Description

I really like the new design of the block editor handbook, but after using it a lot, I've got some feedback/ideas for better search experience:

1. Add keyboard shortcut for searching
On long pages (like a package reference), when you have scrolled down very far, getting back to the search field can be cumbersome. There's no "back to top" button and no keyboard shortcut for using the search field.
A lot of developer documentation provide a Ctrl+K keyboard shortcut to open a search overlay or move focus to the search field. An "internal" example is the WordPress Playground documentation and another one tailwind CSS.
I often find myself switching between different packages/references, and the block editor handbook with references for each package has a very big navigation menu - so anything that makes navigation easier with keyboard would be great.

2. Search Results: show matched text / jump to match

When searching for any keyword, the results do not show how/where the keyword was matched. When clicking on the result, the page opens at the top - requiring the user to use Ctrl+F on the page again. This once again relates to the references and pages being very long and therefore finding the matched keyword/paragraph hard.

Example: Search for useInnerBlocksProps. The first result is the @wordpress/block-editor package reference and useInnerBlocksProps is at the very bottom of the page but the page loads at the top.


I suggest two things:

  • Add an excerpt of the matched text/paragraph to the results view and use some styling (e.g. background color, bold) to highlight the keyword.
  • When clicking on the result, jump to the paragraph/headline the matched text was first found in.

3. More relevant search results
I don't know how the search results are sorted at the moment, but often times I find the more related results at the bottom instead of the top. Maybe we could add some "weights" to keywords? I don't know any technical details - if the editor handbook is built on a standard WP search - but a lot of developer documentation use algolia for that (again the WordPress Playground docs are an example for that).
Or maybe usage of a keyword in a headline is more relevant than in a code example? We could also categorize the results into "API reference", "guides" (just like the main navigation bar on the side)

Examples:

  • Search for getEntityRecords. The first result is the Deprecations page. Which may be relevant, but I guess if I search for the exact method name, I'd want to see the documentation of that method, not of any deprecations. The next result is @wordpress/data - which just has an example of using the function, but not the docs. The real documentation of the function is actually just the fifth element.


  • Search for useBlockProps. "Edit and Save" (4th), "The block wrapper" (5th) and the package (@wordpress/block-editor, 8th) are not the top results. Actually, "RichText Reference" comes before, which seems very unrelated.

I've encountered this many times, but did not write down all the examples. I will extend this list of examples.

Attachments (2)

block-editor-handbook-results-innerblocks.png (38.6 KB) - added by gaambo 8 weeks ago.
block-editor-handbook-results-entityrecords.png (108.8 KB) - added by gaambo 8 weeks ago.

Download all attachments as: .zip

Change History (2)

Note: See TracTickets for help on using tickets.