MkDocs `use_directory_urls: true` bug with `click==8.2.2`

[glenn-jocher]

Context

Latest version of click dependency (released August 2, 2025) is breaking use_directory_urls: true functionality in MkDocs and MkDocs Material.

Bug description

This is causing 404's when clicking on links to previously published pages.

Example Good with click==8.2.1
https://docs-paasvkc6c-ultralytics.vercel.app/models/yolo11/

Example Bad with click==8.2.2
https://docs-paasvkc6c-ultralytics.vercel.app/models/yolo11/index.html

Related links

ultralytics/ultralytics#21568

Reproduction

Reproduce with steps above.

Steps to reproduce

Set use_directory_urls: true in mkdocs.yml with click==8.2.2 installed in environment, then run mkdocs serve.

Browser

Chrome

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 using the built-in info plugin.

[squidfunk]

Hey, thanks for reporting. This must be taken upstream, as I see you already did in mkdocs/mkdocs#4014 and pallets/click#3025. The vercel links require login, so we can't check them. I'll leave it open here for visibility, since I don't know how much time this will take the maintainers of MkDocs and/or click to fix, and where the fix needs to be applied, since the 8.2.2 release notes say:

This is the Click 8.2.2 fix release, which fixes bugs but does not otherwise change behavior and should not result in breaking changes compared to the latest feature release.

Temporary workaround

Limit the version range of click to anything below 8.2.2:

pip install --force-reinstall "click<8.2.2"

[squidfunk]

I've created a minimal reproduction that showcases the problem and added it with further explanations in mkdocs/mkdocs#4014 (comment). Let's hope this gets fixed soon! 🤞

[squidfunk]

Click 8.2.2 was yanked, so it won't be automatically installed when using a version range. This seems to have broken several downstream packages, so it appears the author are working on a fix.

[glenn-jocher]

Thank you @squidfunk!