Skip to content

Conversation

@pawamoy
Copy link
Member

@pawamoy pawamoy commented May 16, 2024

This changes the HTML tags used for auto-references from span to a custom autoref tag. This is made backward compatible by regex-replacing using both the old regex and the new one. The new regex is much, much simpler. Additional HTML attributes are parsed with a proper HTML parser, so ordering does not matter anymore.

Transition period:

  • A new mkdocs-autorefs version is released. It's backward compatible: mkdocstrings handlers (and any other project) will continue working as usual, even if they manually insert autorefs spans in their templates and/or docs.
  • A change is made in mkdocstrings-python (and other handlers) to support the new autoref HTML tag, setting AutorefsPlugin.legacy_refs to False to disable legacy refs (no perf loss). Handlers will require the new version of mkdocs-autorefs in their dependencies.
  • In the future, legacy refs are removed from mkdocs-autorefs, and handlers setting AutorefsPlugin.legacy_refs will be warned by type-checkers that this legacy_refs attribute does not exist anymore. At runtime, it will have no effect.

@pawamoy pawamoy merged commit e142023 into main May 24, 2024
@pawamoy pawamoy deleted the autoref-tag branch May 24, 2024 18:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants