mkdocs-material: Content in embedded files (via Snippets) doesn't show up in search result previews if content includes `` HTML headings

I’ve read the contribution guidelines and agree with them

I’ve found a bug and checked that …

… the problem doesn’t occur with the default MkDocs template
… the problem is not in any of my customizations (CSS, JS, template)
… the documentation does not mention anything about my problem
… there are no open or closed issues that are related to my problem

See the prior discussion at https://github.com/squidfunk/mkdocs-material/discussions/2313, where I was asked by @facelessuser to file this issue.

Description

As soon as file embedded via a snippet contains any <h[1-6]> tag, then the search result previews break in the following way:

None of the text in the snippet (embedded file) is included in the preview.
None of the text in “parent” .md file (that embeds the snippet) that appears after the snippet is included in the preview.

Expected behavior

Search result previews should behave identical, regardless of whether content is directly included in a Markdown file vs. embedded via snippet into that Markdown file.

Actual behavior

See description above, and see screenshots at https://github.com/miguno/mkdocs-search-previews.

Steps to reproduce the bug

See https://github.com/miguno/mkdocs-search-previews for a minimal setup.

Package versions

Python: 3.9.1
MkDocs: 1.1.2
Material: 6.2.8

Project configuration

https://github.com/miguno/mkdocs-search-previews/blob/main/mkdocs.yml

site_name: My Docs

theme:
    name: material

markdown_extensions:
    - pymdownx.snippets:
        base_path: 'docs/'

System information

OS: macOS 10.15.7 Catalina
Browser: Google Chrome v88

About this issue

Original URL
State: closed
Created 3 years ago
Comments: 18 (10 by maintainers)

Most upvoted comments

Ok. Then one final question for you because that’s about Material behavior: If ‘jupiter’ is matched in the first entry in the search index below (JSON), why is the search window in Material showing the shorter text from the second, non-matching entry:

The search_index.json essentially contains the content for each page twice – the anchor-less item contains all content of the whole page. Then, the following items prefixed with the same URL (belonging to the previously mentioned item) contain the content of each section. Thus, when you search for something, and have a match in one section, you will also have a match for the item that contents the whole page. It makes no sense to render both results in the search view – it would be redundant and confusing. This is what MkDocs does in the built-in themes and I personally find it suboptimal from a UX perspective. It’s also why this theme goes to great lengths to kick out the redundant stuff and only present the relevant bits of the page.

Now, it seems that your literal sections are not correctly indexed, because the built-in search plugin does not know what to do with them. This is either by design or an error, so it’s best to ask the maintainers of MkDocs what it is. Regardless of the answer, it’s nothing we can fix on our side. We would need to alter the search behavior, presenting the whole page as a search result, which counteracts what I explained in the last paragraph. If you need to display the whole page result, you may fork the theme and patch the respective behavior.

squidfunk on Mar 1, 2021