question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

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 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:closed
  • Created 3 years ago
  • Comments:18 (10 by maintainers)

github_iconTop GitHub Comments

1reaction
squidfunkcommented, Mar 1, 2021

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.

0reactions
migunocommented, Mar 1, 2021

Other than that, my advice would be to use Markdown level headlines and not literal hx in your integrated Snippets. This will fix the issue on your side.

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.

Read more comments on GitHub >

github_iconTop Results From Across the Web

<h1>–<h6>: The HTML Section Heading elements
Heading information can be used by user agents to construct a table of contents for a document automatically. Do not use heading elements...
Read more >
Google Explains How to Use Headings for SEO
Google's John Mueller offered a clear explanation of how Google uses H1, H2, HTML headings. This explanation shows the role heading elements ...
Read more >
SharePoint Design Manager snippets - Microsoft Learn
Describes how to use snippets and the Snippet Gallery in Design Manager to add SharePoint functionality to HTML master pages or page layout....
Read more >
IDEXX Cornerstone 8.3 User Manual
Information in this document is subject to change without notice. Companies, names and data used in examples are fictitious unless otherwise noted.
Read more >
User Guide - Black Duck - Synopsys
Uploading a scan file using the Black Duck UI. ... Saving search results. ... If the Synopsys Detect (Desktop) does not open after...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found