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
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
Context
I am using
mkdocsas well asmikefor multiple versions of the docs. Code annotations are added based on the documentation (using both# (x)and# (x)!formats. Themkdocs.ymlis reproduced below (as the gitlab repository/project itself is private -- sorry!) as well as the source code for theexamples.mdpage.mkdocs.ymlsite_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.cssBug 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
devversion 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
:hoveris 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
Reproduction
example.zip
Steps to reproduce
mike)Browser
Chrome, Safari, Edge, Firefox
Before submitting