mkdocs-material: Search: compact summaries for long code blocks and lists

I tinkered a little with the search, and following is an idea we can discuss – before shortening text, we would gain a lot if we just remove (or collapse) the list elements that contain no occurrences of a search term. Take for example this query:

Here are all elements that contain no matches (just for illustration, no real UI proposal):

Here is the list with only elements that contain matches:

The looks are still a little meh, because the collapse indicators take too much space. IMHO, it is critical to preserve list numbering, so bullet points would not have different numbers when following up to the page.

This could be extended to code blocks as well. I’m currently thinking about the next big iteration of the search plugin, and we maybe we should move away from making the whole result clickable, because this would allow to make search results completely interactive. We could collapse certain sections, expand them on click, even allow to copy from clipboard.

I’m just thinking out loud. I’ll keep this issue updated when I make progress. Any feedback is appreciated.

I’m going to be honest, it is surprising we replaced the current search wholesale without compact summaries as a minimum requirement. It is quite a bit of a UX regression when used to the previous experience where very quickly at a glance you had lightning fast search and could scan content very quickly as you change your search terms. Now you have to stop, mouse over, search and scroll through pages of content to grok what it is you’re trying to find and it’s not a great experience.

The current implementation is actually more sophisticated than the previous one, as it understands paragraphs and will only show the first two paragraphs which have occurrences that match (e.g. check this query). The CSS workaround will still improve the situation over the previous implementation, because it will be more likely that an occurrence is shown as part of the result. Thus, please apply the CSS workaround for the time being and get the same behavior as before.

I don’t have time to troubleshoot document search as I have a lot of work to do in my own open source community. I’m happy to provide basic info wherever it is helpful though.

I understand. However, we’re only as good as the information we get, and as I said, I’m sure it can be solved. So, if you at some point manage to squeeze in a few minutes, you can open a discussion and somebody can improve the situation with you together. In the meantime, we’ll be working on improving the default and trying to make it even more “out-of-the-box”. Material for MkDocs provides one of the best search implementations without the need for a server that supports 67 languages. Is it perfect? Absolutely not, but we’re working on moving it closer to perfect every day.

I’m sorry that the current implementation does not fit your requirements. I can only say that I’m working tirelessly on the new implementation and we will have something to test drive very soon. The decision to go down the “from scratch” route came up after several change requests came up, all related to search, which cannot be solved with the current architecture. Thus, we decided to stop monkey-patching Lunr.js and solve things the right way.

All of this takes time, but it is currently our highest priority. Thank you for your understanding.

Yes, even just the above would help a lot.

Code blocks are definitely also a dramatic example in our specific use case…when they happen, which is nowhere near as frequently as the lists example. So even just trimming the display of results in lists, like you have above, would be much appreciated.

Thanks for reporting. This is actually not a bug, but definitely yields room for improvement. I’ll check how we can improve search summaries of structured data (lists, code blocks) in the coming months!

I’m sorry that the current implementation does not fit your requirements. I can only say that I’m working tirelessly on the new implementation and we will have something to test drive very soon. The decision to go down the “from scratch” route came up after several change requests came up, all related to search, which cannot be solved with the current architecture. Thus, we decided to stop monkey-patching Lunr.js and solve things the right way.

I was being frank in my feedback but I hope you read my sincerest respect for you, your work and this project. It’s outstanding. Open source is brutal and you my friend are doing great ❤️

First and foremost, amazing product! I searched for something that I can use for our docs that is simple and powerfull and boy, this library is amazing!!

I’m using it in the following site: https://maplibre.org/maplibre-gl-js/docs/

It works great except for one minor thing: I have these html examples here: https://maplibre.org/maplibre-gl-js/docs/examples/

I basically wrote a small script that converts our testing examples to docs so they can be seen in the site, with an iframe and a code block, pretty straight forward.

The problem is that if I search for one of the examples I get the full code in the search results, which doesn’t allow to see other results, this is even worse on mobile device:

Here’s my configuration: https://github.com/maplibre/maplibre-gl-js/blob/main/mkdocs.yml

Thanks for all the amazing work done here!!!

I’ll try the provided CSS fix, but I mainly wanted you to have an example of a production open source documentation project with this issue.

yep, that works much better. thanks.

Understood, and actually one of the most important things on our roadmap for the new search implementation. Here’s an updated version of the previously proposed temporary fix, that reverts the height of the search to the previous behavior:

.md-search-result .md-typeset {
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  max-height: 120px; /* <- adjust to fit */
}