Content in embedded files (via Snippets) doesn't show up in search result previews if content includes `<hX>` HTML headings
See original GitHub issue- 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
Issue Analytics
- State:
- Created 3 years ago
- Comments:18 (10 by maintainers)
Top GitHub Comments
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.
Yeah, I am aware. (And thanks!) The issue I am facing is that auto-generated HTML pages need to be included, created by another tool.