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

[kratsg]

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 © 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.

Related links

• code annotations
• numbering of code annotations

Reproduction

example.zip

Steps to reproduce

1. 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

2. 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.

[squidfunk]

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

1. Fix the formatting in your post – it's jammed
2. 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.
3. Reduce your example to the bare bones – there are too many files.

Then, we're able to look into the problem

[kratsg]

1. Fixed.
2. 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.
3. See (2). Give me a few.

[kratsg]

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

example.zip

[squidfunk]

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]

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]

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

[facelessuser]

@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]

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]

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]

@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]

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]

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]

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

[Aquafina-water-bottle]

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.

• example.zip
• repo link

[squidfunk]

I'll look into it asap, thanks!

[squidfunk]

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

[squidfunk]

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]

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