Content in embedded files (via Snippets) doesn't show up in search result previews

[miguno]

Background
I have a Markdown file that embeds a local HTML file, using Snippets (see Material docs on embedding files).

# Configuration

## Embedding HTML files

!!! success "Embedding external files is supported"
    Everything **below** this line is the embedded output of an embedded HTML file.

--8<-- "documentation/external.html"

Searching this page works. However, search result previews only work for content that is stored directly in the Markdown file. Example of successfully searching for "embedding":

Searching for terms in the embedded HTML file partially works, as the parent page ("Configuration") shows up, but without the useful search result preview as in the previous screenshot. Example of searching for "hostname", which is from the text of the embedded HTML file:

Some of my attempts to fix this issue included:

• Enabling prebuild_index, followed by mkdocs build and serving the output via Apache httpd (nope).
• Adding the external HTML file to nav: in mkdocs.yml (nope). I thought, apparently mistakenly, that the search indexing might be limited to what's explicitly listed there.

Environment

• mkdocs v1.1.2
• mkdocs-material v6.2.8
• mkdocs-material-extensions v1.0.1

Tested with both mkdocs serve (built-in webserver) and serving the output of mkdocs build via Apache httpd.

My question: How can I get the search result previews to work also for embedded files?

[squidfunk]

@facelessuser any idea? I thought Snippets was run as preprocessor, so MkDocs shouldn't see the Snippets but the replaced text?

[squidfunk]

Note that search will first try to highlight a match in a subsection (h2, h3, h4...), and if it doesn't find it, use the h1 as a fallback. Furthermore, the search result summaries are not optimal as they only show the beginning of the text, so if the match is in a later portion, it won't get highlighted, i.e. there are not "..." in the summaries for non-matching parts of the text.

A match in the text directly after the h1 and before any further hx:

A match in any of the subsections:

Improving search result summaries is on the roadmap.

@facelessuser thanks for investigating.

[miguno]

So, in general, only one h1 should be in your document. You can have as many h2+ as you'd like, but h1 should be restricted to one and is used as your title often.

To clarify: This was for testing. I tested with h1, h2, h3, h4, h5, etc. — all have the same result that previews are broken. And it's broken not just for the text between the <hX> tags, but everything else that's in the snippet file.

[squidfunk]

Okay. Then, please file an issue with a minimal reproducible example, starting from a mint Material for MkDocs installation (i.e. minimal mkdocs.yml and no overrides). If we have an example to reproduce the behavior and know exactly what you're aiming for we might either fix the issue or help you make it work. Also please explain exactly what you mean with "broken".

[miguno]

@squidfunk:

Note that search will first try to highlight a match in a subsection (h2, h3, h4...), and if it doesn't find it, use the h1 as a fallback. Furthermore, the search result summaries are not optimal as they only show the beginning of the text, so if the match is in a later portion, it won't get highlighted, i.e. there are not "..." in the summaries for non-matching parts of the text.

Ack, thanks for the info.

But that would still mean that, in my example, "neptune" and "saturn" (plus even "jupiter") would still be expected to show up, no?

[facelessuser]

Yeah, I have no trouble under h2, h3, etc., but I assume there is yet something else that triggers this case. I believe I have seen the described behavior before in some cases, but I cannot seem to put my finger on the exact scenario that caused it.

[miguno]

@facelessuser : Here is a minimal example setup that reproduces the issue. The reproduction isn't 100% to what I described above, but it's close enough and seems to show the underlying cause. README includes description of what "broken" means.

https://github.com/miguno/mkdocs-search-previews

[squidfunk]

Could you please check whether the issue persists when literal hx tags are inserted directly into the page, without using Snippets?

[facelessuser]

Oh, Jupiter also doesn't make it to the Toc. I think raw HTML headers aren't getting handled by Python Markdown and MkDocs the same.

[facelessuser]

Yup, changing to ### Jupiter works.

[facelessuser]

It appears that TOC doesn't handle raw HTML headers.

[squidfunk]

If it's related to and can be isolated to TOC, we must push this upstream to Python Markdown.

[miguno]

Issue created at #2315