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

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</summary

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.

About this issue

Original URL
State: closed
Created a year ago
Comments: 18 (11 by maintainers)

Most upvoted comments

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

squidfunk on May 2, 2023

I’ll look into it asap, thanks!

squidfunk on Apr 17, 2023

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 201054e79 fixes the issue.

squidfunk on May 2, 2023

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.

Aquafina-water-bottle on Apr 15, 2023

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

squidfunk on Mar 6, 2023