All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
%s formatting instead of f-strings in log messages (0cedf9d by Timothée Mazzucotelli).AUTO_REF_RE is renamed AUTOREF_RE (and updated for an improved version of fix_refs)AutoRefInlineProcessor is renamed AutorefsInlineProcessorMkDocsConfig (does not exist on MkDocs 1.3-) (9c15664 by Timothée Mazzucotelli).[`identifier`][] with pymdownx.inlinehilite enabled (e7f2228 by Oleh Prypin). Issue-#34, PR-#40, Co-authored-by: Timothée Mazzucotelli dev@pawamoy.fr__init__ module) (de0670b by Timothée Mazzucotelli). Issue #17, issue mkdocstrings/mkdocstrings#398, PR #18autorefs always, and autorefs-internal or autorefs-external depending on the link (39db59d by Timothée Mazzucotelli). PR #16[``identifier``][], understood as [``identifier``][identifier] (2d3182d by Oleh Prypin). PR #5All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
[Hello World][] -> [hello-world][]) (13428f1 by Timothée Mazzucotelli). Issue-58%s formatting instead of f-strings in log messages (0cedf9d by Timothée Mazzucotelli).AUTO_REF_RE is renamed AUTOREF_RE (and updated for an improved version of fix_refs)AutoRefInlineProcessor is renamed AutorefsInlineProcessorMkDocsConfig (does not exist on MkDocs 1.3-) (9c15664 by Timothée Mazzucotelli).[`identifier`][] with pymdownx.inlinehilite enabled (e7f2228 by Oleh Prypin). Issue-#34, PR-#40, Co-authored-by: Timothée Mazzucotelli dev@pawamoy.fr__init__ module) (de0670b by Timothée Mazzucotelli). Issue #17, issue mkdocstrings/mkdocstrings#398, PR #18autorefs always, and autorefs-internal or autorefs-external depending on the link (39db59d by Timothée Mazzucotelli). PR #16[``identifier``][], understood as [``identifier``][identifier] (2d3182d by Oleh Prypin). PR #5We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
Examples of behavior that contributes to a positive environment for our community include:
Examples of unacceptable behavior include:
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at dev@pawamoy.fr. All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
Community Impact: A violation through a single incident or series of actions.
Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
Community Impact: A serious violation of community standards, including sustained inappropriate behavior.
Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
Consequence: A permanent ban from any sort of public interaction within the community.
This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.
For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
Examples of behavior that contributes to a positive environment for our community include:
Examples of unacceptable behavior include:
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at dev@pawamoy.fr. All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
Community Impact: A violation through a single incident or series of actions.
Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
Community Impact: A serious violation of community standards, including sustained inappropriate behavior.
Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
Consequence: A permanent ban from any sort of public interaction within the community.
This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.
For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
Nothing easier!
Fork and clone the repository, then:
cd mkdocs-autorefs
+ Contributing - mkdocs-autorefs Contributing¤
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
Environment setup¤
Nothing easier!
Fork and clone the repository, then:
cd mkdocs-autorefs
make setup
-
Note
If it fails for some reason, you'll need to install uv manually.
You can install it with:
python3 -m pip install --user pipx
-pipx install uv
-
Now you can try running make setup again, or simply uv install.
You now have the dependencies installed.
Run make help to see all the available actions!
Tasks¤
The entry-point to run commands and tasks is the make Python script, located in the scripts directory. Try running make to show the available commands and tasks. The commands do not need the Python dependencies to be installed, while the tasks do. The cross-platform tasks are written in Python, thanks to duty.
If you work in VSCode, we provide an action to configure VSCode for the project.
Development¤
As usual:
- create a new branch:
git switch -c feature-or-bugfix-name - edit the code and/or the documentation
Before committing:
- run
make format to auto-format the code - run
make check to check everything (fix any warning) - run
make test to run the tests (fix any issue) - if you updated the documentation or the project dependencies:
- run
make docs - go to http://localhost:8000 and check that everything looks good
- follow our commit message convention
If you are unsure about how to fix or ignore a warning, just let the continuous integration fail, and we will help you during review.
Don't bother updating the changelog, we will take care of this.
Commit message convention¤
Commit messages must follow our convention based on the Angular style or the Karma convention:
<type>[(scope)]: Subject
+
Note
If it fails for some reason, you'll need to install uv manually.
You can install it with:
curl -LsSf https://astral.sh/uv/install.sh | sh
+
Now you can try running make setup again, or simply uv sync.
You now have the dependencies installed.
Run make help to see all the available actions!
Tasks¤
The entry-point to run commands and tasks is the make Python script, located in the scripts directory. Try running make to show the available commands and tasks. The commands do not need the Python dependencies to be installed, while the tasks do. The cross-platform tasks are written in Python, thanks to duty.
If you work in VSCode, we provide an action to configure VSCode for the project.
Development¤
As usual:
- create a new branch:
git switch -c feature-or-bugfix-name - edit the code and/or the documentation
Before committing:
- run
make format to auto-format the code - run
make check to check everything (fix any warning) - run
make test to run the tests (fix any issue) - if you updated the documentation or the project dependencies:
- run
make docs - go to http://localhost:8000 and check that everything looks good
- follow our commit message convention
If you are unsure about how to fix or ignore a warning, just let the continuous integration fail, and we will help you during review.
Don't bother updating the changelog, we will take care of this.
Commit message convention¤
Commit messages must follow our convention based on the Angular style or the Karma convention:
<type>[(scope)]: Subject
[Body]
Subject and body must be valid Markdown. Subject must have proper casing (uppercase for first letter if it makes sense), but no dot at the end, and no punctuation in general.
Scope and body are optional. Type can be:
build: About packaging, building wheels, etc.chore: About packaging or repo/files management.ci: About Continuous Integration.deps: Dependencies update.docs: About documentation.feat: New feature.fix: Bug fix.perf: About performance.refactor: Changes that are not features or bug fixes.style: A change in code style/format.tests: About tests.
If you write a body, please add trailers at the end (for example issues and PR references, or co-authors), without relying on GitHub's flavored Markdown:
Body.
@@ -13,4 +12,4 @@
git commit --fixup=SHA
Once all the changes are approved, you can squash your commits:
git rebase -i --autosquash main
And force-push:
git push -f
-
If this seems all too complicated, you can push or force-push each new commit, and we will squash them ourselves if needed, before merging.
\ No newline at end of file
+If this seems all too complicated, you can push or force-push each new commit, and we will squash them ourselves if needed, before merging.
mkdocs-autorefs package.
Automatically link across pages in MkDocs.
Modules:
debug – Debugging utilities.
plugin – This module contains the "mkdocs-autorefs" plugin.
references – Cross-references module.
mkdocs-autorefs package.
Automatically link across pages in MkDocs.
Modules:
debug – Debugging utilities.
plugin – This module contains the "mkdocs-autorefs" plugin.
references – Cross-references module.
This module contains the "mkdocs-autorefs" plugin.
After each page is processed by the Markdown converter, this plugin stores absolute URLs of every HTML anchors it finds to later be able to fix unresolved references. It stores them during the on_page_content event hook.
Just before writing the final HTML to the disc, during the on_post_page event hook, this plugin searches for references of the form [identifier][] or [title][identifier] that were not resolved, and fixes them using the previously stored identifier-URL mapping.
Classes:
AutorefsConfig – Configuration options for the autorefs plugin.
AutorefsPlugin – The autorefs plugin for mkdocs.
Bases: Config
Configuration options for the autorefs plugin.
Attributes:
resolve_closest – Whether to resolve an autoref to the closest URL when multiple URLs are found for an identifier.
class-attribute instance-attribute ¤resolve_closest = Type(bool, default=False)
+ mkdocs_autorefs.plugin - mkdocs-autorefs
This module contains the "mkdocs-autorefs" plugin.
After each page is processed by the Markdown converter, this plugin stores absolute URLs of every HTML anchors it finds to later be able to fix unresolved references. It stores them during the on_page_content event hook.
Just before writing the final HTML to the disc, during the on_post_page event hook, this plugin searches for references of the form [identifier][] or [title][identifier] that were not resolved, and fixes them using the previously stored identifier-URL mapping.
Classes:
-
AutorefsConfig – Configuration options for the autorefs plugin.
-
AutorefsPlugin – The autorefs plugin for mkdocs.
Bases: Config
Configuration options for the autorefs plugin.
Attributes:
-
resolve_closest – Whether to resolve an autoref to the closest URL when multiple URLs are found for an identifier.
class-attribute instance-attribute ¤
resolve_closest = Type(bool, default=False)
Whether to resolve an autoref to the closest URL when multiple URLs are found for an identifier.
By closest, we mean a combination of "relative to the current page" and "shortest distance from the current page".
For example, if you link to identifier hello from page foo/bar/, and the identifier is found in foo/, foo/baz/ and foo/bar/baz/qux/ pages, autorefs will resolve to foo/bar/baz/qux, which is the only URL relative to foo/bar/.
If multiple URLs are equally close, autorefs will resolve to the first of these equally close URLs. If autorefs cannot find any URL that is close to the current page, it will log a warning and resolve to the first URL found.
When false and multiple URLs are found for an identifier, autorefs will log a warning and resolve to the first URL.
AutorefsPlugin()
-
Bases: BasePlugin[AutorefsConfig]
The autorefs plugin for mkdocs.
This plugin defines the following event hooks:
on_configon_page_contenton_post_page
Check the Developing Plugins page of mkdocs for more information about its plugin system.
Methods:
-
get_item_url – Return a site-relative URL with anchor to the identifier, if it's present anywhere.
-
map_urls – Recurse on every anchor to map its ID to its absolute URL.
-
on_config – Instantiate our Markdown extension.
-
on_page_content – Map anchors to URLs.
-
on_page_markdown – Remember which page is the current one.
-
on_post_page – Fix cross-references.
-
register_anchor – Register that an anchor corresponding to an identifier was encountered when rendering the page.
-
register_url – Register that the identifier should be turned into a link to this URL.
Source code in src/mkdocs_autorefs/plugin.py
94
-95
-96
-97
-98
-99
def __init__(self) -> None:
+
Bases: BasePlugin[AutorefsConfig]
The autorefs plugin for mkdocs.
This plugin defines the following event hooks:
on_configon_page_contenton_post_page
Check the Developing Plugins page of mkdocs for more information about its plugin system.
Methods:
-
get_item_url – Return a site-relative URL with anchor to the identifier, if it's present anywhere.
-
map_urls – Recurse on every anchor to map its ID to its absolute URL.
-
on_config – Instantiate our Markdown extension.
-
on_page_content – Map anchors to URLs.
-
on_page_markdown – Remember which page is the current one.
-
on_post_page – Fix cross-references.
-
register_anchor – Register that an anchor corresponding to an identifier was encountered when rendering the page.
-
register_url – Register that the identifier should be turned into a link to this URL.
Attributes:
-
get_fallback_anchor (Callable[[str], tuple[str, ...]] | None) – Fallback anchors getter.
Source code in src/mkdocs_autorefs/plugin.py
83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
def __init__(self) -> None:
"""Initialize the object."""
super().__init__()
- self._url_map: dict[str, list[str]] = {}
+
+ # The plugin uses three URL maps, one for "primary" URLs, one for "secondary" URLs,
+ # and one for "absolute" URLs.
+ #
+ # - A primary URL is an identifier that links to a specific anchor on a page.
+ # - A secondary URL is an alias of an identifier that links to the same anchor as the identifier's primary URL.
+ # Primary URLs with these aliases as identifiers may or may not be rendered later.
+ # - An absolute URL is an identifier that links to an external resource.
+ # These URLs are typically registered by mkdocstrings when loading object inventories.
+ #
+ # For example, mkdocstrings registers a primary URL for each heading rendered in a page.
+ # Then, for each alias of this heading's identifier, it registers a secondary URL.
+ #
+ # We need to keep track of whether an identifier is primary or secondary,
+ # to give it precedence when resolving cross-references.
+ # We wouldn't want to log a warning if there is a single primary URL and one or more secondary URLs,
+ # instead we want to use the primary URL without any warning.
+ #
+ # - A single primary URL mapped to an identifer? Use it.
+ # - Multiple primary URLs mapped to an identifier? Use the first one, or closest one if configured as such.
+ # - No primary URL mapped to an identifier, but a secondary URL mapped? Use it.
+ # - Multiple secondary URLs mapped to an identifier? Use the first one, or closest one if configured as such.
+ # - No secondary URL mapped to an identifier? Try using absolute URLs
+ # (typically registered by loading inventories in mkdocstrings).
+ #
+ # This logic unfolds in `_get_item_url`.
+ self._primary_url_map: dict[str, list[str]] = {}
+ self._secondary_url_map: dict[str, list[str]] = {}
self._abs_url_map: dict[str, str] = {}
- self.get_fallback_anchor: Callable[[str], tuple[str, ...]] | None = None
-
get_item_url(
+ # YORE: Bump 2: Remove line.
+ self._get_fallback_anchor: Callable[[str], tuple[str, ...]] | None = None
+
property writable ¤
Fallback anchors getter.
get_item_url(
identifier: str,
from_url: str | None = None,
- fallback: Callable[[str], Sequence[str]] | None = None,
+ fallback: Callable[[str], Sequence[str]] | None = None,
) -> str
-
Return a site-relative URL with anchor to the identifier, if it's present anywhere.
Parameters:
-
identifier (str) – The anchor (without '#').
-
from_url (str | None, default: None ) – The URL of the base page, from which we link towards the targeted pages.
-
fallback (Callable[[str], Sequence[str]] | None, default: None ) – An optional function to suggest alternative anchors to try on failure.
Returns:
-
str – A site-relative URL.
Source code in src/mkdocs_autorefs/plugin.py
188
-189
-190
-191
-192
-193
-194
-195
-196
-197
-198
-199
-200
-201
-202
-203
-204
-205
-206
-207
-208
-209
def get_item_url(
+
Return a site-relative URL with anchor to the identifier, if it's present anywhere.
Parameters:
-
identifier (str) – The anchor (without '#').
-
from_url (str | None, default: None ) – The URL of the base page, from which we link towards the targeted pages.
Returns:
-
str – A site-relative URL.
Source code in src/mkdocs_autorefs/plugin.py
237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
def get_item_url(
self,
identifier: str,
from_url: str | None = None,
+ # YORE: Bump 2: Remove line.
fallback: Callable[[str], Sequence[str]] | None = None,
) -> str:
"""Return a site-relative URL with anchor to the identifier, if it's present anywhere.
@@ -48,58 +107,58 @@
Arguments:
identifier: The anchor (without '#').
from_url: The URL of the base page, from which we link towards the targeted pages.
- fallback: An optional function to suggest alternative anchors to try on failure.
Returns:
A site-relative URL.
"""
- url = self._get_item_url(identifier, fallback, from_url)
+ # YORE: Bump 2: Replace `, fallback` with `` within line.
+ url = self._get_item_url(identifier, from_url, fallback)
if from_url is not None:
parsed = urlsplit(url)
if not parsed.scheme and not parsed.netloc:
return relative_url(from_url, url)
return url
map_urls(base_url: str, anchor: AnchorLink) -> None
-
Recurse on every anchor to map its ID to its absolute URL.
This method populates self.url_map by side-effect.
Parameters:
-
base_url (str) – The base URL to use as a prefix for each anchor's relative URL.
-
anchor (AnchorLink) – The anchor to process and to recurse on.
Source code in src/mkdocs_autorefs/plugin.py
265
-266
-267
-268
-269
-270
-271
-272
-273
-274
-275
-276
def map_urls(self, base_url: str, anchor: AnchorLink) -> None:
+
Recurse on every anchor to map its ID to its absolute URL.
This method populates self._primary_url_map by side-effect.
Parameters:
-
base_url (str) – The base URL to use as a prefix for each anchor's relative URL.
-
anchor (AnchorLink) – The anchor to process and to recurse on.
Source code in src/mkdocs_autorefs/plugin.py
315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
def map_urls(self, base_url: str, anchor: AnchorLink) -> None:
"""Recurse on every anchor to map its ID to its absolute URL.
- This method populates `self.url_map` by side-effect.
+ This method populates `self._primary_url_map` by side-effect.
Arguments:
base_url: The base URL to use as a prefix for each anchor's relative URL.
anchor: The anchor to process and to recurse on.
"""
- self.register_anchor(base_url, anchor.id)
+ self.register_anchor(base_url, anchor.id, primary=True)
for child in anchor.children:
self.map_urls(base_url, child)
on_config(config: MkDocsConfig) -> MkDocsConfig | None
-
Instantiate our Markdown extension.
Hook for the on_config event. In this hook, we instantiate our AutorefsExtension and add it to the list of Markdown extensions used by mkdocs.
Parameters:
-
config (MkDocsConfig) – The MkDocs config object.
Returns:
-
MkDocsConfig | None – The modified config.
Source code in src/mkdocs_autorefs/plugin.py
211
-212
-213
-214
-215
-216
-217
-218
-219
-220
-221
-222
-223
-224
-225
-226
def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
+
Instantiate our Markdown extension.
Hook for the on_config event. In this hook, we instantiate our AutorefsExtension and add it to the list of Markdown extensions used by mkdocs.
Parameters:
-
config (MkDocsConfig) – The MkDocs config object.
Returns:
-
MkDocsConfig | None – The modified config.
Source code in src/mkdocs_autorefs/plugin.py
261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
"""Instantiate our Markdown extension.
Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
@@ -118,27 +177,27 @@
Map anchors to URLs.
Hook for the on_page_content event. In this hook, we map the IDs of every anchor found in the table of contents to the anchors absolute URLs. This mapping will be used later to fix unresolved reference of the form [title][identifier] or [identifier][].
Parameters:
-
html (str) – HTML converted from Markdown.
-
page (Page) – The related MkDocs page instance.
-
kwargs (Any, default: {} ) – Additional arguments passed by MkDocs.
Returns:
-
str – The same HTML. We only use this hook to map anchors to URLs.
Source code in src/mkdocs_autorefs/plugin.py
243
-244
-245
-246
-247
-248
-249
-250
-251
-252
-253
-254
-255
-256
-257
-258
-259
-260
-261
-262
-263
def on_page_content(self, html: str, page: Page, **kwargs: Any) -> str: # noqa: ARG002
+
Map anchors to URLs.
Hook for the on_page_content event. In this hook, we map the IDs of every anchor found in the table of contents to the anchors absolute URLs. This mapping will be used later to fix unresolved reference of the form [title][identifier] or [identifier][].
Parameters:
-
html (str) – HTML converted from Markdown.
-
page (Page) – The related MkDocs page instance.
-
kwargs (Any, default: {} ) – Additional arguments passed by MkDocs.
Returns:
-
str – The same HTML. We only use this hook to map anchors to URLs.
Source code in src/mkdocs_autorefs/plugin.py
293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
def on_page_content(self, html: str, page: Page, **kwargs: Any) -> str: # noqa: ARG002
"""Map anchors to URLs.
Hook for the [`on_page_content` event](https://www.mkdocs.org/user-guide/plugins/#on_page_content).
@@ -162,20 +221,20 @@
Remember which page is the current one.
Parameters:
-
markdown (str) – Input Markdown.
-
page (Page) – The related MkDocs page instance.
-
kwargs (Any, default: {} ) – Additional arguments passed by MkDocs.
Returns:
-
str – The same Markdown. We only use this hook to keep a reference to the current page URL, used during Markdown conversion by the anchor scanner tree processor.
Source code in src/mkdocs_autorefs/plugin.py
228
-229
-230
-231
-232
-233
-234
-235
-236
-237
-238
-239
-240
-241
def on_page_markdown(self, markdown: str, page: Page, **kwargs: Any) -> str: # noqa: ARG002
+
Remember which page is the current one.
Parameters:
-
markdown (str) – Input Markdown.
-
page (Page) – The related MkDocs page instance.
-
kwargs (Any, default: {} ) – Additional arguments passed by MkDocs.
Returns:
-
str – The same Markdown. We only use this hook to keep a reference to the current page URL, used during Markdown conversion by the anchor scanner tree processor.
Source code in src/mkdocs_autorefs/plugin.py
278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
def on_page_markdown(self, markdown: str, page: Page, **kwargs: Any) -> str: # noqa: ARG002
"""Remember which page is the current one.
Arguments:
@@ -190,38 +249,40 @@
self.current_page = page.url
return markdown
Fix cross-references.
Hook for the on_post_page event. In this hook, we try to fix unresolved references of the form [title][identifier] or [identifier][]. Doing that allows the user of autorefs to cross-reference objects in their documentation strings. It uses the native Markdown syntax so it's easy to remember and use.
We log a warning for each reference that we couldn't map to an URL, but try to be smart and ignore identifiers that do not look legitimate (sometimes documentation can contain strings matching our AUTO_REF_RE regular expression that did not intend to reference anything). We currently ignore references when their identifier contains a space or a slash.
Parameters:
-
output (str) – HTML converted from Markdown.
-
page (Page) – The related MkDocs page instance.
-
kwargs (Any, default: {} ) – Additional arguments passed by MkDocs.
Returns:
-
str – Modified HTML.
Source code in src/mkdocs_autorefs/plugin.py
278
-279
-280
-281
-282
-283
-284
-285
-286
-287
-288
-289
-290
-291
-292
-293
-294
-295
-296
-297
-298
-299
-300
-301
-302
-303
-304
-305
-306
-307
-308
-309
def on_post_page(self, output: str, page: Page, **kwargs: Any) -> str: # noqa: ARG002
+
Fix cross-references.
Hook for the on_post_page event. In this hook, we try to fix unresolved references of the form [title][identifier] or [identifier][]. Doing that allows the user of autorefs to cross-reference objects in their documentation strings. It uses the native Markdown syntax so it's easy to remember and use.
We log a warning for each reference that we couldn't map to an URL, but try to be smart and ignore identifiers that do not look legitimate (sometimes documentation can contain strings matching our AUTO_REF_RE regular expression that did not intend to reference anything). We currently ignore references when their identifier contains a space or a slash.
Parameters:
-
output (str) – HTML converted from Markdown.
-
page (Page) – The related MkDocs page instance.
-
kwargs (Any, default: {} ) – Additional arguments passed by MkDocs.
Returns:
-
str – Modified HTML.
Source code in src/mkdocs_autorefs/plugin.py
328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
def on_post_page(self, output: str, page: Page, **kwargs: Any) -> str: # noqa: ARG002
"""Fix cross-references.
Hook for the [`on_post_page` event](https://www.mkdocs.org/user-guide/plugins/#on_post_page).
@@ -244,7 +305,9 @@
"""
log.debug("Fixing references in page %s", page.file.src_path)
+ # YORE: Bump 2: Replace `, fallback=self.get_fallback_anchor` with `` within line.
url_mapper = functools.partial(self.get_item_url, from_url=page.url, fallback=self.get_fallback_anchor)
+ # YORE: Bump 2: Replace `, _legacy_refs=self.legacy_refs` with `` within line.
fixed_output, unmapped = fix_refs(output, url_mapper, _legacy_refs=self.legacy_refs)
if unmapped and log.isEnabledFor(logging.WARNING):
@@ -254,42 +317,52 @@
return fixed_output
register_anchor(
- page: str, identifier: str, anchor: str | None = None
+ page: str,
+ identifier: str,
+ anchor: str | None = None,
+ *,
+ primary: bool = True
) -> None
-
Register that an anchor corresponding to an identifier was encountered when rendering the page.
Parameters:
-
page (str) – The relative URL of the current page. Examples: 'foo/bar/', 'foo/index.html'
-
identifier (str) – The HTML anchor (without '#') as a string.
Source code in src/mkdocs_autorefs/plugin.py
101
-102
-103
-104
-105
-106
-107
-108
-109
-110
-111
-112
-113
def register_anchor(self, page: str, identifier: str, anchor: str | None = None) -> None:
+
Register that an anchor corresponding to an identifier was encountered when rendering the page.
Parameters:
-
page (str) – The relative URL of the current page. Examples: 'foo/bar/', 'foo/index.html'
-
identifier (str) – The identifier to register.
-
anchor (str | None, default: None ) – The anchor on the page, without #. If not provided, defaults to the identifier.
-
primary (bool, default: True ) – Whether this anchor is the primary one for the identifier.
Source code in src/mkdocs_autorefs/plugin.py
136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
def register_anchor(self, page: str, identifier: str, anchor: str | None = None, *, primary: bool = True) -> None:
"""Register that an anchor corresponding to an identifier was encountered when rendering the page.
Arguments:
page: The relative URL of the current page. Examples: `'foo/bar/'`, `'foo/index.html'`
- identifier: The HTML anchor (without '#') as a string.
+ identifier: The identifier to register.
+ anchor: The anchor on the page, without `#`. If not provided, defaults to the identifier.
+ primary: Whether this anchor is the primary one for the identifier.
"""
page_anchor = f"{page}#{anchor or identifier}"
- if identifier in self._url_map:
- if page_anchor not in self._url_map[identifier]:
- self._url_map[identifier].append(page_anchor)
+ url_map = self._primary_url_map if primary else self._secondary_url_map
+ if identifier in url_map:
+ if page_anchor not in url_map[identifier]:
+ url_map[identifier].append(page_anchor)
else:
- self._url_map[identifier] = [page_anchor]
+ url_map[identifier] = [page_anchor]
Register that the identifier should be turned into a link to this URL.
Parameters:
-
identifier (str) – The new identifier.
-
url (str) – The absolute URL (including anchor, if needed) where this item can be found.
Source code in src/mkdocs_autorefs/plugin.py
115
-116
-117
-118
-119
-120
-121
-122
def register_url(self, identifier: str, url: str) -> None:
+
Register that the identifier should be turned into a link to this URL.
Parameters:
-
identifier (str) – The new identifier.
-
url (str) – The absolute URL (including anchor, if needed) where this item can be found.
Source code in src/mkdocs_autorefs/plugin.py
153
+154
+155
+156
+157
+158
+159
+160
def register_url(self, identifier: str, url: str) -> None:
"""Register that the identifier should be turned into a link to this URL.
Arguments:
@@ -297,4 +370,4 @@
url: The absolute URL (including anchor, if needed) where this item can be found.
"""
self._abs_url_map[identifier] = url
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/reference/mkdocs_autorefs/references/index.html b/reference/mkdocs_autorefs/references/index.html
index 56aac2c..9174868 100644
--- a/reference/mkdocs_autorefs/references/index.html
+++ b/reference/mkdocs_autorefs/references/index.html
@@ -1,4 +1,4 @@
- mkdocs_autorefs.references - mkdocs-autorefs
Cross-references module.
Classes:
-
AnchorScannerTreeProcessor – Tree processor to scan and register HTML anchors.
-
AutorefsExtension – Markdown extension that transforms unresolved references into auto-references.
-
AutorefsHookInterface – An interface for hooking into how AutoRef handles inline references.
-
AutorefsInlineProcessor – A Markdown extension to handle inline references.
Functions:
-
fix_ref – Return a repl function for re.sub.
-
fix_refs – Fix all references in the given HTML text.
-
relative_url – Compute the relative path from URL A to URL B.
Attributes:
-
AUTOREF_RE – The autoref HTML tag regular expression.
-
AUTO_REF_RE – Deprecated. Use AUTOREF_RE instead.
module-attribute ¤
AUTOREF_RE = compile(
+ mkdocs_autorefs.references - mkdocs-autorefs
Cross-references module.
Classes:
-
AnchorScannerTreeProcessor – Tree processor to scan and register HTML anchors.
-
AutorefsExtension – Markdown extension that transforms unresolved references into auto-references.
-
AutorefsHookInterface – An interface for hooking into how AutoRef handles inline references.
-
AutorefsInlineProcessor – A Markdown extension to handle inline references.
Functions:
-
fix_ref – Return a repl function for re.sub.
-
fix_refs – Fix all references in the given HTML text.
-
relative_url – Compute the relative path from URL A to URL B.
Attributes:
-
AUTOREF_RE – The autoref HTML tag regular expression.
-
AUTO_REF_RE – Deprecated. Use AUTOREF_RE instead.
module-attribute ¤
AUTOREF_RE = compile(
"<autoref (?P<attrs>.*?)>(?P<title>.*?)</autoref>",
flags=DOTALL,
)
@@ -9,14 +9,14 @@
Deprecated. Use AUTOREF_RE instead.
AnchorScannerTreeProcessor(
plugin: AutorefsPlugin, md: Markdown | None = None
)
-
Bases: Treeprocessor
Tree processor to scan and register HTML anchors.
Parameters:
-
plugin (AutorefsPlugin) – A reference to the autorefs plugin, to use its register_anchor method.
Source code in src/mkdocs_autorefs/references.py
427
-428
-429
-430
-431
-432
-433
-434
def __init__(self, plugin: AutorefsPlugin, md: Markdown | None = None) -> None:
+
Bases: Treeprocessor
Tree processor to scan and register HTML anchors.
Parameters:
-
plugin (AutorefsPlugin) – A reference to the autorefs plugin, to use its register_anchor method.
Source code in src/mkdocs_autorefs/references.py
469
+470
+471
+472
+473
+474
+475
+476
def __init__(self, plugin: AutorefsPlugin, md: Markdown | None = None) -> None:
"""Initialize the tree processor.
Parameters:
@@ -27,19 +27,19 @@
AutorefsExtension(
plugin: AutorefsPlugin | None = None, **kwargs: Any
)
-
Bases: Extension
Markdown extension that transforms unresolved references into auto-references.
Auto-references are then resolved later by the MkDocs plugin.
This extension also scans Markdown anchors ([](){#some-id}) to register them with the MkDocs plugin.
Parameters:
-
plugin (AutorefsPlugin | None, default: None ) – An optional reference to the autorefs plugin (to pass it to the anchor scanner tree processor).
-
**kwargs (Any, default: {} ) – Keyword arguments passed to the base constructor.
Methods:
-
extendMarkdown – Register the extension.
Source code in src/mkdocs_autorefs/references.py
503
-504
-505
-506
-507
-508
-509
-510
-511
-512
-513
-514
-515
def __init__(
+
Bases: Extension
Markdown extension that transforms unresolved references into auto-references.
Auto-references are then resolved later by the MkDocs plugin.
This extension also scans Markdown anchors ([](){#some-id}) to register them with the MkDocs plugin.
Parameters:
-
plugin (AutorefsPlugin | None, default: None ) – An optional reference to the autorefs plugin (to pass it to the anchor scanner tree processor).
-
**kwargs (Any, default: {} ) – Keyword arguments passed to the base constructor.
Methods:
-
extendMarkdown – Register the extension.
Source code in src/mkdocs_autorefs/references.py
545
+546
+547
+548
+549
+550
+551
+552
+553
+554
+555
+556
+557
def __init__(
self,
plugin: AutorefsPlugin | None = None,
**kwargs: Any,
@@ -53,28 +53,28 @@
super().__init__(**kwargs)
self.plugin = plugin
extendMarkdown(md: Markdown) -> None
-
Register the extension.
Add an instance of our AutorefsInlineProcessor to the Markdown parser. Also optionally add an instance of our AnchorScannerTreeProcessor to the Markdown parser if a reference to the autorefs plugin was passed to this extension.
Parameters:
-
md (Markdown) – A markdown.Markdown instance.
Source code in src/mkdocs_autorefs/references.py
517
-518
-519
-520
-521
-522
-523
-524
-525
-526
-527
-528
-529
-530
-531
-532
-533
-534
-535
-536
-537
-538
def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name)
+
Register the extension.
Add an instance of our AutorefsInlineProcessor to the Markdown parser. Also optionally add an instance of our AnchorScannerTreeProcessor to the Markdown parser if a reference to the autorefs plugin was passed to this extension.
Parameters:
-
md (Markdown) – A markdown.Markdown instance.
Source code in src/mkdocs_autorefs/references.py
559
+560
+561
+562
+563
+564
+565
+566
+567
+568
+569
+570
+571
+572
+573
+574
+575
+576
+577
+578
+579
+580
def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name)
"""Register the extension.
Add an instance of our [`AutorefsInlineProcessor`][mkdocs_autorefs.references.AutorefsInlineProcessor] to the Markdown parser.
@@ -104,15 +104,15 @@
lineno: int,
)
The context around an auto-reference.
Methods:
-
as_dict – Convert the context to a dictionary of HTML attributes.
Convert the context to a dictionary of HTML attributes.
Source code in src/mkdocs_autorefs/references.py
79
-80
-81
-82
+
Convert the context to a dictionary of HTML attributes.
Source code in src/mkdocs_autorefs/references.py
82
83
84
85
86
-87
def as_dict(self) -> dict[str, str]:
+87
+88
+89
+90
def as_dict(self) -> dict[str, str]:
"""Convert the context to a dictionary of HTML attributes."""
return {
"domain": self.domain,
@@ -122,18 +122,18 @@
"lineno": str(self.lineno),
}
abstractmethod ¤
Expand an identifier in a given context.
Parameters:
-
identifier (str) – The identifier to expand.
Returns:
-
str – The expanded identifier.
Source code in src/mkdocs_autorefs/references.py
89
-90
-91
-92
-93
-94
-95
-96
-97
-98
-99
@abstractmethod
-def expand_identifier(self, identifier: str) -> str:
+
Expand an identifier in a given context.
Parameters:
-
identifier (str) – The identifier to expand.
Returns:
-
str – The expanded identifier.
Source code in src/mkdocs_autorefs/references.py
92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
@abstractmethod
+def expand_identifier(self, identifier: str) -> str:
"""Expand an identifier in a given context.
Parameters:
@@ -144,15 +144,15 @@
"""
raise NotImplementedError
abstractmethod ¤
get_context() -> Context
-
Get the current context.
Returns:
-
Context – The current context.
Source code in src/mkdocs_autorefs/references.py
101
-102
-103
-104
+
Get the current context.
Returns:
-
Context – The current context.
Source code in src/mkdocs_autorefs/references.py
104
105
106
107
-108
@abstractmethod
-def get_context(self) -> AutorefsHookInterface.Context:
+108
+109
+110
+111
@abstractmethod
+def get_context(self) -> AutorefsHookInterface.Context:
"""Get the current context.
Returns:
@@ -160,91 +160,13 @@
"""
raise NotImplementedError
Bases: ReferenceInlineProcessor
A Markdown extension to handle inline references.
Methods:
-
evalId – Evaluate the id portion of [ref][id].
-
handleMatch – Handle an element that matched.
Source code in src/mkdocs_autorefs/references.py
117
-118
def __init__(self, *args: Any, **kwargs: Any) -> None: # noqa: D107
+
Bases: ReferenceInlineProcessor
A Markdown extension to handle inline references.
Methods:
-
handleMatch – Handle an element that matched.
Source code in src/mkdocs_autorefs/references.py
120
+121
def __init__(self, *args: Any, **kwargs: Any) -> None: # noqa: D107
super().__init__(REFERENCE_RE, *args, **kwargs)
-
Evaluate the id portion of [ref][id].
If [ref][] use [ref].
Parameters:
-
data (str) – The data to evaluate.
-
index (int) – The starting position.
-
text (str) – The text to use when no identifier.
Returns:
-
tuple[str | None, int, bool] – A tuple containing the identifier, its end position, and whether it matched.
Source code in src/mkdocs_autorefs/references.py
149
-150
-151
-152
-153
-154
-155
-156
-157
-158
-159
-160
-161
-162
-163
-164
-165
-166
-167
-168
-169
-170
-171
-172
-173
-174
-175
-176
-177
-178
-179
-180
-181
-182
-183
-184
-185
def evalId(self, data: str, index: int, text: str) -> tuple[str | None, int, bool]: # noqa: N802 (parent's casing)
- """Evaluate the id portion of `[ref][id]`.
-
- If `[ref][]` use `[ref]`.
-
- Arguments:
- data: The data to evaluate.
- index: The starting position.
- text: The text to use when no identifier.
-
- Returns:
- A tuple containing the identifier, its end position, and whether it matched.
- """
- m = self.RE_LINK.match(data, pos=index)
- if not m:
- return None, index, False
-
- identifier = m.group(1)
- if not identifier:
- identifier = text
- # Allow the entire content to be one placeholder, with the intent of catching things like [`Foo`][].
- # It doesn't catch [*Foo*][] though, just due to the priority order.
- # https://github.com/Python-Markdown/markdown/blob/1858c1b601ead62ed49646ae0d99298f41b1a271/markdown/inlinepatterns.py#L78
- if match := INLINE_PLACEHOLDER_RE.fullmatch(identifier):
- stashed_nodes: dict[str, Element | str] = self.md.treeprocessors["inline"].stashed_nodes # type: ignore[attr-defined]
- el = stashed_nodes.get(match[1])
- if isinstance(el, Element) and el.tag == "code":
- identifier = "".join(el.itertext())
- # Special case: allow pymdownx.inlinehilite raw <code> snippets but strip them back to unhighlighted.
- if match := HTML_PLACEHOLDER_RE.fullmatch(identifier):
- stash_index = int(match.group(1))
- html = self.md.htmlStash.rawHtmlBlocks[stash_index]
- identifier = markupsafe.Markup(html).striptags()
- self.md.htmlStash.rawHtmlBlocks[stash_index] = escape(identifier)
-
- end = m.end(0)
- return identifier, end, True
-
Handle an element that matched.
Parameters:
Returns:
Source code in src/mkdocs_autorefs/references.py
123
-124
-125
+
Handle an element that matched.
Parameters:
Returns:
Source code in src/mkdocs_autorefs/references.py
125
126
127
128
@@ -266,7 +188,8 @@
144
145
146
-147
def handleMatch(self, m: Match[str], data: str) -> tuple[Element | None, int | None, int | None]: # type: ignore[override] # noqa: N802
+147
+148
def handleMatch(self, m: Match[str], data: str) -> tuple[Element | None, int | None, int | None]: # type: ignore[override] # noqa: N802
"""Handle an element that matched.
Arguments:
@@ -280,59 +203,21 @@
if not handled:
return None, None, None
- identifier, end, handled = self.evalId(data, index, text)
+ identifier, slug, end, handled = self._eval_id(data, index, text)
if not handled or identifier is None:
return None, None, None
- if re.search(r"[\x00-\x1f]", identifier):
- # Do nothing if the matched reference contains control characters (from 0 to 31 included).
- # Specifically `\x01` is used by Python-Markdown HTML stash when there's inline formatting,
- # but references with Markdown formatting are not possible anyway.
+ if slug is None and re.search(r"[\x00-\x1f]", identifier):
+ # Do nothing if the matched reference still contains control characters (from 0 to 31 included)
+ # that weren't unstashed when trying to compute a slug of the title.
return None, m.start(0), end
- return self._make_tag(identifier, text), m.start(0), end
+ return self._make_tag(identifier, text, slug=slug), m.start(0), end
fix_ref(
url_mapper: Callable[[str], str],
unmapped: list[tuple[str, Context | None]],
) -> Callable
-
Return a repl function for re.sub.
In our context, we match Markdown references and replace them with HTML links.
When the matched reference's identifier was not mapped to an URL, we append the identifier to the outer unmapped list. It generally means the user is trying to cross-reference an object that was not collected and rendered, making it impossible to link to it. We catch this exception in the caller to issue a warning.
Parameters:
-
url_mapper (Callable[[str], str]) – A callable that gets an object's site URL by its identifier, such as mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url.
-
unmapped (list[tuple[str, Context | None]]) – A list to store unmapped identifiers.
Returns:
-
Callable – The actual function accepting a Match object
-
Callable – and returning the replacement strings.
Source code in src/mkdocs_autorefs/references.py
339
-340
-341
-342
-343
-344
-345
-346
-347
-348
-349
-350
-351
-352
-353
-354
-355
-356
-357
-358
-359
-360
-361
-362
-363
-364
-365
-366
-367
-368
-369
-370
-371
-372
-373
-374
-375
-376
+
Return a repl function for re.sub.
In our context, we match Markdown references and replace them with HTML links.
When the matched reference's identifier was not mapped to an URL, we append the identifier to the outer unmapped list. It generally means the user is trying to cross-reference an object that was not collected and rendered, making it impossible to link to it. We catch this exception in the caller to issue a warning.
Parameters:
-
url_mapper (Callable[[str], str]) – A callable that gets an object's site URL by its identifier, such as mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url.
-
unmapped (list[tuple[str, Context | None]]) – A list to store unmapped identifiers.
Returns:
-
Callable – The actual function accepting a Match object
-
Callable – and returning the replacement strings.
Source code in src/mkdocs_autorefs/references.py
376
377
378
379
@@ -347,7 +232,50 @@
388
389
390
-391
def fix_ref(
+391
+392
+393
+394
+395
+396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
+417
+418
+419
+420
+421
+422
+423
+424
+425
+426
+427
+428
+429
+430
+431
+432
+433
+434
def fix_ref(
url_mapper: Callable[[str], str],
unmapped: list[tuple[str, AutorefsHookInterface.Context | None]],
) -> Callable:
@@ -369,23 +297,29 @@
and returning the replacement strings.
"""
- def inner(match: Match) -> str:
+ def inner(match: Match) -> str:
title = match["title"]
attrs = _html_attrs_parser.parse(f"<a {match['attrs']}>")
identifier: str = attrs["identifier"]
+ slug = attrs.get("slug", None)
optional = "optional" in attrs
hover = "hover" in attrs
+ identifiers = (identifier, slug) if slug else (identifier,)
+
try:
- url = url_mapper(unescape(identifier))
+ url = _find_url(identifiers, url_mapper)
except KeyError:
if optional:
+ log.debug("Unresolved optional cross-reference: %s", identifier)
if hover:
return f'<span title="{identifier}">{title}</span>'
return title
unmapped.append((identifier, attrs.context))
if title == identifier:
return f"[{identifier}][]"
+ if title == f"<code>{identifier}</code>" and not slug:
+ return f"[<code>{identifier}</code>][]"
return f"[{title}][{identifier}]"
parsed = urlsplit(url)
@@ -403,37 +337,36 @@
fix_refs(
html: str,
url_mapper: Callable[[str], str],
- *,
- _legacy_refs: bool = True
+ _legacy_refs: bool = True,
) -> tuple[str, list[tuple[str, Context | None]]]
-
Fix all references in the given HTML text.
Parameters:
-
html (str) – The text to fix.
-
url_mapper (Callable[[str], str]) – A callable that gets an object's site URL by its identifier, such as mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url.
Returns:
-
tuple[str, list[tuple[str, Context | None]]] – The fixed HTML, and a list of unmapped identifiers (string and optional context).
Source code in src/mkdocs_autorefs/references.py
395
-396
-397
-398
-399
-400
-401
-402
-403
-404
-405
-406
-407
-408
-409
-410
-411
-412
-413
-414
-415
-416
-417
-418
def fix_refs(
+
Fix all references in the given HTML text.
Parameters:
-
html (str) – The text to fix.
-
url_mapper (Callable[[str], str]) – A callable that gets an object's site URL by its identifier, such as mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url.
Returns:
-
tuple[str, list[tuple[str, Context | None]]] – The fixed HTML, and a list of unmapped identifiers (string and optional context).
Source code in src/mkdocs_autorefs/references.py
437
+438
+439
+440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
+452
+453
+454
+455
+456
+457
+458
+459
+460
def fix_refs(
html: str,
url_mapper: Callable[[str], str],
- *,
- _legacy_refs: bool = True,
+ # YORE: Bump 2: Remove line.
+ _legacy_refs: bool = True, # noqa: FBT001, FBT002
) -> tuple[str, list[tuple[str, AutorefsHookInterface.Context | None]]]:
"""Fix all references in the given HTML text.
@@ -454,30 +387,30 @@
return html, unmapped
Compute the relative path from URL A to URL B.
Parameters:
Returns:
-
str – The relative URL to go from A to B.
Source code in src/mkdocs_autorefs/references.py
206
-207
-208
-209
-210
-211
-212
-213
-214
-215
-216
-217
-218
-219
-220
-221
-222
-223
-224
-225
-226
-227
-228
-229
def relative_url(url_a: str, url_b: str) -> str:
+