Anchor validation and special characters.

KITMohi commented 2 weeks ago

Hi and thank you for the great project!

I've noticed an unexpected behavior with the new anchor validation features where headers contain special characters, specifically "&".

Here is a reproducible sample with 1.6.0

mkdocs.yml:

site_name: Test Docs
validation:
  unrecognized_links: warn
  not_found: warn
  anchors: warn

docs/index.md

# Title

- [Title](#title)
  - [Sub-title](#sub-title)
  - [Conclusion & Future Work](#conclusion--future-work)

## Sub-title

## Conclusion & Future Work

And here's the error I get:

mkdocs serve --strict
INFO    -  Building documentation...
INFO    -  Cleaning site directory
WARNING -  edit_uri: 'edit/main/docs/index.md' is not a valid URL, it should include the http:// (scheme)
WARNING -  Doc file 'index.md' contains a link '#conclusion--future-work', but there is no such anchor on this page.

It's worth noting that it's a TOC generated by VSCode.

pawamoy commented 2 weeks ago

Hello, thanks for the report :) Could you tell us what the actual anchor is when you serve your docs? VSCode probably doesn't slugify the same way as Python-Markdown does.

pawamoy commented 2 weeks ago

Yep, here's the anchor I get when serving my docs with a Conclusion & Future Work heading: #conclusion-future-work. In short, the anchors generated by VSCode do not match the ones generated by MkDocs. So the anchor validation warning is right. I'd recommend always checking the anchors by serving your docs and looking at them in a browser. I'll close this but feel free to comment further!

mkdocs / mkdocs

Anchor validation and special characters. #3704