code annotations trigger a jump to the annotation upon clicking (in non-latest docs) #5160

kratsg · 2023-03-06T15:35:23Z

Context

I am using mkdocs as well as mike for multiple versions of the docs. Code annotations are added based on the documentation (using both # (x) and # (x)! formats. The mkdocs.yml is reproduced below (as the gitlab repository/project itself is private -- sorry!) as well as the source code for the examples.md page.

mkdocs.yml

site_name: itkdb
site_description: Python wrapper for ITk Production Database API
site_author: Giordon Stark
site_url: https://itkdb.docs.cern.ch
repo_name: atlas-itk/sw/db/itkdb
repo_url: https://gitlab.cern.ch/atlas-itk/sw/db/itkdb
edit_uri: edit/main/docs
copyright: "Copyright &copy; Giordon Stark 2018-present"

docs_dir: docs
site_dir: site
theme:
  name: material
  custom_dir: docs/.overrides
  language: en
  favicon: assets/images/logo.svg
  icon:
    repo: fontawesome/brands/gitlab
    logo: material/language-python
    edit: material/pencil
  font:
    text: Roboto
    code: Roboto Mono
  palette:
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: blue
      accent: light-blue
      toggle:
        icon: material/weather-night
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: blue
      accent: light-blue
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
  features:
    - navigation.sections
    - navigation.expand
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.instant
    - content.action.edit
    - content.code.copy
    - content.code.annotate

nav:
  - Home:
      - About: index.md
      - Installation: install.md
      - Configuration: config.md
      - Examples: examples.md
      - Meta:
          - Changelog: history.md
          - FAQ: meta/faq.md
          - Authors: meta/authors.md
  - Reference:
      - API: reference/api/
      - CLI:
          - itkdb: reference/cli/

watch:
  - src/itkdb

plugins:
  # Built-in
  search: {}
  # Extra
  glightbox: {}
  minify:
    minify_html: true
  git-revision-date-localized:
    type: date
    # Required for generated documentation from gen-files
    fallback_to_build_date: true
  mike:
    alias_type: copy
  gen-files:
    scripts:
      - docs/reference/gen_ref_nav.py
      - docs/macros.py # https://github.com/facelessuser/pymdown-extensions/issues/933
  literate-nav:
    nav_file: SUMMARY.txt
  section-index: {}
  mkdocstrings:
    default_handler: python
    handlers:
      python:
        paths:
          - src
        options:
          # Headings
          show_root_heading: true
          show_root_full_path: false
          # Docstrings
          docstring_style: google
          docstring_options:
            ignore_init_summary: true
          # Signatures/annotations
          show_if_no_docstring: true
          merge_init_into_class: true
          separate_signature: true
          show_signature_annotations: true
          show_source: true
          # Other
          filters:
            - "!__all__"
            - "!^_[^_]"
  # to add redirects
  #redirects:
  #  redirect_maps:
  #    old.md: new_path/old.md

markdown_extensions:
  # Built-in
  - markdown.extensions.abbr:
  - markdown.extensions.admonition:
  - markdown.extensions.attr_list:
  - markdown.extensions.footnotes:
  - markdown.extensions.meta:
  - markdown.extensions.tables:
  - markdown.extensions.toc:
      permalink: true
  # Extra
  - mkdocs-click:
  - pymdownx.arithmatex:
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret:
  - pymdownx.critic:
  - pymdownx.details:
  - pymdownx.emoji:
      # https://github.com/twitter/twemoji
      # https://raw.githubusercontent.com/facelessuser/pymdown-extensions/master/pymdownx/twemoji_db.py
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.highlight:
      guess_lang: false
      linenums_style: pymdownx-inline
      use_pygments: true
  - pymdownx.inlinehilite:
  - pymdownx.keys:
  - pymdownx.magiclink:
      repo_url_shortener: true
      repo_url_shorthand: true
      social_url_shortener: true
      social_url_shorthand: true
      normalize_issue_symbols: true
      provider: gitlab
      user: atlas-itk/sw/db
      repo: itkdb
  - pymdownx.mark:
  - pymdownx.progressbar:
  - pymdownx.saneheaders:
  - pymdownx.smartsymbols:
  - pymdownx.snippets:
      check_paths: true
      base_path:
        - docs/.snippets
        - README.md
      auto_append:
        - links.txt
        - abbrs.txt
  - pymdownx.superfences:
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde:
  - mdx_truly_sane_lists: # for 2-space indented lists, https://github.com/mkdocs/mkdocs/issues/545

extra:
  version:
    provider: mike
    default: latest
  social:
    - icon: fontawesome/brands/github-alt
      link: https://github.com/kratsg
extra_css:
  - assets/css/custom.css
  - https://cdn.jsdelivr.net/gh/tonsky/FiraCode@5.2/distr/fira_code.css

Bug description

When clicking on annotations from our examples page -- the annotation is correctly showing (and the URL does not change). When doing the exact procedure from the dev version of the docs -- the click triggers the anchor to be appended to the URL, page scroll/jumps to the annotation, and then clicking again shows the annotation.

Of note, if I click the annotation outside of the anchor tag (but within the rectangle of the annotation itself as soon as the :hover is triggeed), I am able to get the annotation to show without the anchor being clicked -- so this somehow indicates to me there must be some event bubbling/click that does not get its propagation stopped perhaps.

Reproduction

example.zip

Steps to reproduce

Build docs (with multiple versions using mike)

mike deploy --config-file mkdocs.yml --branch gh-pages-debug --update-aliases 0.4 latest
mike deploy --config-file mkdocs.yml --branch gh-pages-debug --update-aliases dev

Click annotations on a rendered page and see that page jumps if on a non-latest version

Browser

Chrome, Safari, Edge, Firefox

Before submitting

I have read and followed the bug reporting guidelines.
I have attached links to the documentation, and possibly related issues and discussions.
I assure that I have removed all customizations before submitting this bug report.
I have attached a .zip file with a minimal reproduction.

The text was updated successfully, but these errors were encountered:

squidfunk · 2023-03-06T15:44:15Z

Thanks for reporting. Sadly, this issue is missing too much information. I kindly ask you to complete the following steps:

Fix the formatting in your post – it's jammed
Provide detailed instructions for "build with multiple versions using mike" – we need to know exactly what you did. Provide step-by-step instructions (yes, there will likely be many steps), or we can't help.
Reduce your example to the bare bones – there are too many files.

Then, we're able to look into the problem

kratsg · 2023-03-06T15:50:03Z

Fixed.
This one is tricky without access to the repo but I'll see if I can reproduce smaller than using the example.zip without the full repo + tags. I need a few minutes.
See (2). Give me a few.

kratsg · 2023-03-06T16:00:06Z

This version apparently also causes jumping with the latest as well. Is this simple/short enough?

example.zip

squidfunk · 2023-03-06T19:14:48Z

This is still not a minimal example. There are 160 lines of MkDocs configuration with 9 plugins. Please remove everything that is not necessary. It really needs to be the smallest possible reproduction that showcases the issues.

For more guidance follow our reproduction guide.

maxsitt · 2023-03-11T12:38:06Z

I can report the exact same problem from my page: annotation jump. Build with latest mkdocs-material-9.1.2. Tested in Firefox and Chrome.

Configuration: mkdocs.yml

I have only two plugins (search, glightbox) installed.

squidfunk · 2023-03-11T15:47:33Z

I would've investigated this error days ago, still no reproduction...

facelessuser · 2023-03-11T16:02:28Z

@squidfunk you can reproduce with @maxsitt's link above. Granted, I don't know what else is in their project, but I can at least reproduce the behavior on Mac Chrome.

With that said, a stripped down reproduce would be better, see.

squidfunk · 2023-03-11T16:51:14Z

Yes, I've already observed it in the link from the OP, but I still need something small that I can run. I'm very sorry to ask, but with 20k+ users, I've got so many things on my plate that I need to ask for users to provide runnable examples that don't force me to install hundreds of dependencies. I hope for your understanding. From there on, it's likely an easy fix.

maxsitt · 2023-03-11T20:00:18Z

I tried to reproduce the bug in a minimal example, but even with exactly the same configuration (mkdocs.yml) I can not reproduce the annotation jump.

However, if navigation.instant is activated, the code annotation is not rendered at all.
If search.highlight is activated, no text is appearing when clicking the annotation.

example.zip

squidfunk · 2023-03-12T10:12:51Z

@maxsitt thanks for the reproduction – however, the example you provided works perfectly (with both instant loading and highlighting enabled) and I'm unable to observe what's been reported in the OP (see video). We still can't rule out that this behavior is triggered by a third-party plugin or a configuration that is not officially supported by Material for MkDocs.

Ohne.Titel.mp4

I can't stress it enough: please follow the bug reporting guide – it explains the necessary steps. Since we didn't receive a reproduction that showcases the problem in this issue after asking for it multiple times, we're closing it as not reproducible, and thus incomplete. We can reopen it once we have something runnable. Until then, it would be guessing.

maxsitt · 2023-03-14T12:09:18Z

Sorry for not being able to provide a reproducible example.

Deactivating navigation.instant and search.highlight fixed the problem and is my workaround for the moment.

HydrogenSulfate · 2023-04-07T02:52:43Z

Sorry for not being able to provide a reproducible example.

Deactivating navigation.instant and search.highlight fixed the problem and is my workaround for the moment.

Same problem for me, and thx much for your workaround solution, "Deactivating navigation.instant and search.highlight" did works.

squidfunk · 2023-04-07T07:58:05Z

We're still waiting for a reproduction that showcases the issue. Happy to reopen and fix this issue then.

Aquafina-water-bottle · 2023-04-15T01:22:12Z

Hey @squidfunk,

Does the following reproduction work for you? I was able to reproduce the issue and upload it to https://aquafina-water-bottle.github.io/mkdocs-material-5160 as proof of concept (scroll down a bit to see the annotation). It affects me on both Firefox and Chrome. In particular, when clicking on the annotation multiple times, it doesn't seem to toggle it like it does on the current page, and rather flashes between un-toggled and toggled.

squidfunk · 2023-04-17T09:26:49Z

I'll look into it asap, thanks!

squidfunk · 2023-05-02T08:41:19Z

@Aquafina-water-bottle thanks for the excellent reproduction – I'm finally able to observe the issue.

squidfunk · 2023-05-02T09:00:42Z

Okay, I think I found the problem – there's an interference between the two event listeners – on the code annotation (omitting the navigation) and on the body (intercepting all clicks for instant loading). It looks like we need to use Event.stopPropagation to omit the event from being dispatched to the instant loading handler.

Instant loading was recently refactored in 9.1.1, but we still need to refactor how we handle/dispatch anchor navigation. We'll tackle this later this year after the current features that are developed (improved social cards and search) are released. Until then, my testing shows that 201054e fixes the issue.

squidfunk · 2023-05-02T09:33:48Z

9.1.9 is out, including the changes referenced in this issue! 🚀

squidfunk added the needs input Issue needs further input by the reporter label Mar 6, 2023

squidfunk added bug Issue reports a bug needs reproduction Issue lacks a minimal reproduction .zip file and removed needs input Issue needs further input by the reporter labels Mar 6, 2023

squidfunk closed this as completed Mar 12, 2023

HydrogenSulfate mentioned this issue Apr 7, 2023

Add cylinder2d unsteady re100 PaddlePaddle/PaddleScience#241

Merged

squidfunk reopened this May 2, 2023

squidfunk added needs investigation Issue must be investigated by the maintainers and removed needs reproduction Issue lacks a minimal reproduction .zip file labels May 2, 2023

squidfunk removed the needs investigation Issue must be investigated by the maintainers label May 2, 2023

squidfunk added the resolved Issue is resolved, yet unreleased if open label May 2, 2023

squidfunk closed this as completed May 2, 2023

HydrogenSulfate mentioned this issue May 5, 2023

Refine contribute doc PaddlePaddle/PaddleScience#285

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

code annotations trigger a jump to the annotation upon clicking (in non-latest docs) #5160

code annotations trigger a jump to the annotation upon clicking (in non-latest docs) #5160

kratsg commented Mar 6, 2023 •

edited

squidfunk commented Mar 6, 2023

kratsg commented Mar 6, 2023 •

edited

kratsg commented Mar 6, 2023

squidfunk commented Mar 6, 2023 •

edited

maxsitt commented Mar 11, 2023 •

edited

squidfunk commented Mar 11, 2023

facelessuser commented Mar 11, 2023

squidfunk commented Mar 11, 2023 •

edited

maxsitt commented Mar 11, 2023

squidfunk commented Mar 12, 2023 •

edited

maxsitt commented Mar 14, 2023

HydrogenSulfate commented Apr 7, 2023 •

edited

squidfunk commented Apr 7, 2023

Aquafina-water-bottle commented Apr 15, 2023

squidfunk commented Apr 17, 2023

squidfunk commented May 2, 2023

squidfunk commented May 2, 2023

squidfunk commented May 2, 2023

code annotations trigger a jump to the annotation upon clicking (in non-latest docs) #5160

code annotations trigger a jump to the annotation upon clicking (in non-latest docs) #5160

Comments

kratsg commented Mar 6, 2023 • edited

Context

Bug description

Related links

Reproduction

Steps to reproduce

Browser

Before submitting

squidfunk commented Mar 6, 2023

kratsg commented Mar 6, 2023 • edited

kratsg commented Mar 6, 2023

squidfunk commented Mar 6, 2023 • edited

maxsitt commented Mar 11, 2023 • edited

squidfunk commented Mar 11, 2023

facelessuser commented Mar 11, 2023

squidfunk commented Mar 11, 2023 • edited

maxsitt commented Mar 11, 2023

squidfunk commented Mar 12, 2023 • edited

maxsitt commented Mar 14, 2023

HydrogenSulfate commented Apr 7, 2023 • edited

squidfunk commented Apr 7, 2023

Aquafina-water-bottle commented Apr 15, 2023

squidfunk commented Apr 17, 2023

squidfunk commented May 2, 2023

squidfunk commented May 2, 2023

squidfunk commented May 2, 2023

kratsg commented Mar 6, 2023 •

edited

kratsg commented Mar 6, 2023 •

edited

squidfunk commented Mar 6, 2023 •

edited

maxsitt commented Mar 11, 2023 •

edited

squidfunk commented Mar 11, 2023 •

edited

squidfunk commented Mar 12, 2023 •

edited

HydrogenSulfate commented Apr 7, 2023 •

edited