Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Anchor validation false positives after upgrading to 1.6 #3690

Open
squidfunk opened this issue Apr 29, 2024 · 1 comment
Open

Anchor validation false positives after upgrading to 1.6 #3690

squidfunk opened this issue Apr 29, 2024 · 1 comment

Comments

@squidfunk
Copy link
Sponsor Contributor

First of all, thanks for the very useful new anchor validation feature! Upgrading to MkDocs 1.6, I was able to fix many stale anchors in our documentation. However, in the process, I came across a few false positives – the anchors are correct, but MkDocs reports them nonetheless. This is particularly the case when using the Tabbed extension with combine_header_slug, which allows to prepend the slug of the nearest header to the tab.

I believe this needs to be fixed in MkDocs, since it might be some kind of ordering issue when running anchor validation, but I'm tagging @facelessuser here for visibility. By using the Tabbed extension, anchor links to tabs are much more readable, something that many users asked for on the Material for MkDocs issue tracker.

Example

The following example is used for illustration. You can also download it here: anchor-validation-bug.zip

index.md

# Page with tabs

## Headline

=== "Tab A"

    Anchor for this tab is `#headline-tab-a`

=== "Tab B"

    Anchor for this tab is `#headline-tab-b`

foo.md

# Links to tabs

- [Tab A](index.md#headline-tab-a)
- [Tab B](index.md#headline-tab-b)

MkDocs will not detect those links and report them as non-existent:

INFO    -  Cleaning site directory
INFO    -  Doc file 'foo.md' contains a link 'index.md#headline-tab-a', but the doc 'index.md' does not contain an anchor '#headline-tab-a'.
INFO    -  Doc file 'foo.md' contains a link 'index.md#headline-tab-b', but the doc 'index.md' does not contain an anchor '#headline-tab-b'.
INFO    -  Documentation built in 0.12 seconds

When running the example, it's easy to see that anchor are correct and work as expected.

@pawamoy
Copy link
Sponsor Contributor

pawamoy commented Jun 10, 2024

pymdownx Tabbed seems to register its treeprocessor updating anchors (slugs) with priority 4.

https://github.com/facelessuser/pymdown-extensions/blob/c8856a3bca3840b538ae3d03298a7d6ecf279541/pymdownx/tabbed.py#L416

...while MkDocs registers its treeprocessor reading anchors with priority 5.

md.treeprocessors.register(self, "mkdocs_extract_anchors", priority=5) # Same as 'toc'.

It means MkDocs gets anchors before Tabbed had a chance to update them. To fix this, either Tabbed should increase its treeprocessor priority, or MkDocs should lower its own (or both). The MkDocs priority has to be strictly lower than pymdownx's.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants