search

squidfunk / mkdocs-material

Documentation that simply works
https://squidfunk.github.io/mkdocs-material/
MIT License
20.25k stars 3.47k forks source link

Instant Preview w/ Content Tab #6875

Closed santaimpersonator closed 6 months ago

santaimpersonator commented 6 months ago

Context

No response

Bug description

When enabling the instant preview feature, the rendering of a linked content tab only show the tabs and not the content below: image

Related links

Reproduction

Unfortunately, the build file for the reproduction was 80MB (and too big); probably due to all the images stored. (*I'll work on processing my commits to the project, so I can submit a reproduction later this week)

However, the site can be reproduced from our repository: https://github.com/sparkfun/SparkFun_GNSS_mosaic-X5

Just enable the instant preview feature globally:

# Configuration for webpage theme
theme:
  # Features to Include (ref. theme documentation)
  features:
    # Enables instant previews globally, for all internal links
    - navigation.instant.preview

Steps to reproduce

  1. Clone our repo: https://github.com/sparkfun/SparkFun_GNSS_mosaic-X5
  2. Enable the instant preview feature globally in the mkdocs.yml file 
    # Configuration for webpage theme
theme:
  # Features to Include (ref. theme documentation)
  features:
    # Enables instant previews globally, for all internal links
    - navigation.instant.preview
  3. Install the mkdocs-material v9.5.12 + insiders v4.53.0
  4. Install the required plugins (or disable them in the mkdocs.yml file) 
    sudo apt-get install pngquant
pip install mkdocs-monorepo-plugin mkdocs-redirects mkdocs-git-authors-plugin mkdocs-git-revision-date-localized-plugin mkdocs-git-committers-plugin-2 Pillow 'mkdocs-material[imaging]'
  5. Serve the site locally 
    mkdocs serve
  6. Navigate to a section, where the PPS Output section is linked and hover over it

Browser

Chrome

Before submitting

squidfunk commented 6 months ago

Thanks for reporting. When creating a minimal reproduction, you should not pack up your site but create a new project with the smallest possible content that showcases the problem. It is absolutely mandatory to provide a minimal reproduction, so we can investigate. We cannot work on a site with hundreds or thousands of pages – it just takes too long.

squidfunk commented 6 months ago

I'll work on processing my commits to the project, so I can submit a reproduction later this week

We'll reopen this issue when we receive a proper reproduction. Without a reproduction, it is unclear whether the problem is within our code base or hides within your customizations. As can be seen from the screenshots, your site seems to customize Material for MkDocs quite heavily. Closing as incomplete.

santaimpersonator commented 6 months ago

@squidfunk I understand the need for a reproduction, which is why I originally left that box unchecked. I just needed some time to get all my commits sorted out, so I didn't lose my work. Sometimes GitHub Desktop gets confused when I copy a repository 😅

I reduced the reproduction without the customizations. I have uploaded the file and updated the reproduction steps (but not the images).

Reproduction

9.5.13+insiders.4.53.1-tabs-issue.zip

Steps to reproduce

  1. Install the mkdocs-material-insiders
  2. Serve the site locally 
    mkdocs serve
  3. Navigate to a section, where the PPS Output section is linked and hover over it

Browser

Chrome DuckDuckGo

squidfunk commented 6 months ago

Thanks for the reproduction. It's still 17 MB due to the images, but I will check if we can work with it.

santaimpersonator commented 6 months ago

Here is a more basic doc with just the tabbed content and instant preview features:

9.5.13+insiders.4.53.1-really-basic.zip

Issue

When you hover over the link... you only see the tab title and not of the content: image

squidfunk commented 6 months ago

Thanks! I'll look into it ☺️

squidfunk commented 6 months ago

Thanks again for reporting and providing the excellent reproduction. Contrary to the title of the reproduction that might have assumed this is a really basic issue, I'm afraid it isn't. Linking of instant previews is currently limited to sites and sections within that site. It does not work with linked content tabs because of how the HTML is structured.

Instant previews fetch the site they point to, then search for the anchor which currently must point to a headline, and extract all content until the next headline. The structure (schematic) is:

Headline#id-1
Content for Headline#id-1

Headline#id-2
Content for Headline#id-2

...

It currently does not work with generic anchors, and it will likely never work with tabs, because of the kind of "odd" HTML structure to make tabs work without JavaScript. The structure for content tabs is:

Tabs
  TabControl#id-1
  TabControl#id-2
  ...
  TabLabels
    TabLabel for TabControl#id-1
    TabLabel for TabControl#id-2
    ...
  TabContent
    TabContent for TabControl#id-1
    TabContent for TabControl#id-2
    ...

This means that we would need to somehow add very specific logic to support referencing of the content associated with a tab to instant previews, which is (currently) too much of an ask. We're still iterating on the basic mechanics and need to keep the scope limited, first fixing all issues we encounter with the current basic functionality, which we then can evaluate to extend later on. Material for MkDocs is used by thousands of users, and everybody uses it a little differently, so we always try to start with a sharp focus and slowly expand once incoming bugs start to cease.

Thus, it's currently not planned, but we will re-evaluate once we consider instant previews stable ☺️ I've adjusted the documentation to better reflect those limitations in fdeafbb87.