⚠️ Next version will start considering identifiers containing spaces and slashes

[pawamoy]

Until now, mkdocs-autorefs ignored reference markup that used spaces or slashes in the identifier. All the following references, if not already resolved during Markdown conversion, would be ignored by autorefs:

[whatever][hello/world]
[whatever][hello world]

[hello/world][]
[hello world][]

[`hello/world`][]
[`hello world`][]

Next version will start considering them, which means users might get warnings that some references cannot be resolved.

WARNING -  mkdocs_autorefs: index.md: Could not find cross-reference target '[hello/world]'
WARNING -  mkdocs_autorefs: index.md: Could not find cross-reference target '[hello world]'

If these references aren't intentional (you happen to be using the reference syntax by accident), the solution is to escape them, or to just use different syntax:

Instead of [hello world][], you can:

- wrap in inline code: `[hello world][]`
- use different syntax? [hello world]<>, (hello world)(), etc.

This change is necessary because identifiers in Sphinx-like object inventories may contain spaces and slashes, so we must support these identifiers in mkdocs-autorefs. Issue tracked here: #55. The previous decision to consider such identifiers "unintentional references" was arbitrary.

This change, even though it can make CI fail, will not be considered a breaking change, because:

• It doesn't prevent building and deploying your docs. It only makes strict builds fail (mkdocs build/serve -s), and strict builds are opt-in. More details on this reasoning here: Warning logs and strict mode mkdocs/mkdocs#3818.
• I do not expect a lot of project to be impacted.
• Markdown documents/docstrings shouldn't use the reference Markdown syntax for things that are not references: this change will warn about such occurrences so you can use different markup.
• Considering it a breaking change would require a transition period, where INFO logs are emitted, configuration options added to opt into the new behavior, then default behavior switched, then configuration options removed, etc.: a lot of maintenance. Even doing so wouldn't prevent breaking CI because INFO logs are easy to miss. This even happens after long periods of time during which deprecation warnings are mistakenly ignored.

This announcement therefore serves as an official communication that warnings (logs and actual warnings) are not to be considered part of the public/stable API. I will add this to the docs too.

Thank you for your understanding!