search

squidfunk / mkdocs-material

Documentation that simply works
https://squidfunk.github.io/mkdocs-material/
MIT License
20.12k stars 3.47k forks source link

Documentation on how to use search #5557

Closed mark-heptinstall closed 1 year ago

mark-heptinstall commented 1 year ago

Description

The existing documentation focuses on setting up search and the blog on how it works but I don't see anything in practical terms of how someone should be using the search to get the best results.

I want to provide our users with some reference material on how to use the site search effectively. They have no interest in the configuration or technical aspects of searching.

The documentation does state it uses lunr and their documentation has a page on searching though that wasn't immediately obvious to me as a newbie. This is a good reference and it would be great to see this in the context of the mkdocs-material search and UI.

I'm also using tags, after looking at the lunr page I now realise I can restrict search terms to tags only by prefixing with tags: which I don't find in the documentation on setting up tags.

Related links

-Setting up site search -Setting up tags

Proposed change

No response

Before submitting

squidfunk commented 1 year ago

Thank for suggesting. I absolutely agree! Part of this was already asked in #4982, but since we're currently re-architecting the entire search experience, it's likely that the syntax will change, so we need to wait for the new search to be finished. We should not advertise functionality that will not be part of the new search, which in particular applies to syntax that is possible to use (supported by Lunr.js), but that is practically never used. We'll be replacing Lunr.js with a custom implementation in the near future, which will yield a much better search UX without the necessity to use the rather cryptic syntax. This is actively being worked on, but as you can imagine, writing a new search engine from scratch will take us a little more time ☺️

karengermond commented 1 year ago

Hi @squidfunk, when will you be replacing the search engine? My team would like me to replace the search engine but I want to wait to try out your custom implementation.

squidfunk commented 1 year ago

We're working on it, but it'll take some more time. We currently can't put a precise estimate on it, but it'll be later this year.

karengermond commented 1 year ago

Thanks for the update!

squidfunk commented 1 year ago

We came to the conclusion that we're not going to document how to use search, i.e., to write a primer on the specific syntax from lunr.js – the reason is that our aim is to create a search that does not need you to know a syntax to use it, and/or makes it easy for you to learn modifiers from just using it. We might re-evaluate in the future, but for now, this is not planned.