Search: compact summaries for long code blocks and lists

[feasgal]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I've found a bug and checked that ...

• ... the problem doesn't occur with the mkdocs or readthedocs themes
• ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
• ... the documentation does not mention anything about my problem
• ... there are no open or closed issues that are related to my problem

Description

The search results preview displays the whole <ol> or <ul>, regardless of where in the list the result appears. This makes for a lot of scrolling in the results. I first commented about this on #3053 in April, because I mistakenly thought I was getting the entire page in the result. Now that I've narrowed it down, I'm back with a new issue as requested.

Expected behaviour

Similar to results that appear in a plain paragraph, I would expect the search preview to display the <li> in which the search term appears. If the <li> includes multiple paragraphs, maybe even just the relevant <p>.

Actual behaviour

I have an ordered list, several of whose list items contain nested, unordered lists. See attached lorem ipsum file long_search_result.md

When served or built, if I search for TN2206, I get the entire <ol> in the preview, with its nested unordered lists, even though TN2206 only appears once in the <ol>, as the last word of the last <li> in the last <ul> in the last <ol>.

When served or built, if I search for cras, I get the entire <ol> in the preview, with its nested unordered lists, even though cras only appears once in the <ol>, in the first <li> of the top <ol>.

Steps to reproduce

1. Serve or build an MkDocs project containing long_search_result.md.
2. Search the served/built docs for TN2206.
3. Search the served/built docs for cras.

Package versions

• Python: Python 3.10.0
• MkDocs: mkdocs, version 1.3.0 from /Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/mkdocs (Python 3.10)
• Material: Version: 8.4.0+insiders.4.21.1

Configuration

site_name: Long Search Results
site_url: "https://example.com/docs"

plugins:
    - search:
        separator: '[\s\-/\\]+'
    - offline

nav:
    - Example: long_search_result.md
    
theme:
 name: material


markdown_extensions:
   - smarty
   - admonition

System information

• Operating system: macOS Monterey Version 12.4
• Browser: Google Chrome Version 104.0.5112.101 (Official Build) (x86_64)

[squidfunk]

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!

[squidfunk]

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.

[feasgal]

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.

[TristisOris]

i was confused a bit, because your own blog say that search truncated to 320 symbols, but it not. https://squidfunk.github.io/mkdocs-material/blog/2021/09/13/search-better-faster-smaller/#search-previews

[squidfunk]

@TristisOris the old search truncated to 320 characters, the new (current) one doesn't:

This was due to the fact that search previews were truncated after a maximum of 320 characters, ...

[squidfunk]

Since this was asked multiple times, here's a mitigation for the overly large previews that reverts to the pre-v9 behavior of Material for MkDocs, truncating search after three lines (albeit you can change this value). Just add the following CSS:

.md-search-result .md-typeset {
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
}

[TristisOris]

[Just add the following CSS]

This break some blocks and show empty info. And can't truncate lists, code, etc.

so best balanced option for now - use as is.

[squidfunk]

@TristisOris could you please elaborate?

[TristisOris]

@squidfunk

[squidfunk]

Thanks, give me some time to check how we can omit the behavior mentioned.

[ekoleda-codaio]

+1 to this issue. The search suggestions for my docs can be very long, to the point where it dramatically hurts the utility of the search functionality.

[squidfunk]

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 */
}