feature: Allow choosing whether to set title HTML attributes on links
#62
Assignees
Labels
feature
New feature or request
Comments
|
Related: squidfunk/mkdocs-material#8019 |
pawamoy
added a commit
that referenced
this issue
Feb 22, 2025
This change adds a `link_titles` option that defaults to `"auto"`. In automatic mode, link titles are either: - always set if Material for MkDocs and its instant preview feature aren't detected - only set on external links otherwise (since instant preview are not supported on external links anyway) The option also accepts the `True` and `False`, for always/never setting titles, respectively. An update to the title logic accompanies this change in order to make use of recorded heading titles (a change brought two commit ago): - optional cross-references will use the original title, and optionally append the identifier if it doesn't already appear in the title - mandatory cross-references will use either the original title if there's one, or no title at all This is because optional cross-refs are almost exclusively created by mkdocstrings handlers, and therefore displaying the identifier (full qualified name of objects) is useful when hovering on a link. Manual cross-references on the other hand can often be references to text sections, and should never display the section anchor. The limitation being that manual cross-references to API objects won't show the identifier. We could consider using an additional attribute (other than `optional`) to label cross-refs as "API objects" or not, though users would still have to annotate their manual cross-refs with such an attribute to enjoy the appended identifier to the title. Issue-33: #33 Issue-62: #62
pawamoy
added a commit
that referenced
this issue
Feb 23, 2025
This change adds a `link_titles` option that defaults to `"auto"`. In automatic mode, link titles are either: - always set if Material for MkDocs and its instant preview feature aren't detected - only set on external links otherwise (since instant preview are not supported on external links anyway) The option also accepts the `True` and `False`, for always/never setting titles, respectively. An update to the title logic accompanies this change in order to make use of recorded heading titles (a change brought two commit ago): - optional cross-references will use the original title, and optionally append the identifier if it doesn't already appear in the title - mandatory cross-references will use either the original title if there's one, or no title at all This is because optional cross-refs are almost exclusively created by mkdocstrings handlers, and therefore displaying the identifier (full qualified name of objects) is useful when hovering on a link. Manual cross-references on the other hand can often be references to text sections, and should never display the section anchor. The limitation being that manual cross-references to API objects won't show the identifier. We could consider using an additional attribute (other than `optional`) to label cross-refs as "API objects" or not, though users would still have to annotate their manual cross-refs with such an attribute to enjoy the appended identifier to the title. Issue-33: #33 Issue-62: #62
pawamoy
added a commit
that referenced
this issue
Feb 23, 2025
This change adds a `link_titles` option that defaults to `"auto"`. In automatic mode, link titles are either: - always set if Material for MkDocs and its instant preview feature aren't detected - only set on external links otherwise (since instant preview are not supported on external links anyway) The option also accepts the `True` and `False`, for always/never setting titles, respectively. An update to the title logic accompanies this change in order to make use of recorded heading titles (a change brought two commit ago): - optional cross-references will use the original title, and optionally append the identifier if it doesn't already appear in the title - mandatory cross-references will use either the original title if there's one, or no title at all This is because optional cross-refs are almost exclusively created by mkdocstrings handlers, and therefore displaying the identifier (full qualified name of objects) is useful when hovering on a link. Manual cross-references on the other hand can often be references to text sections, and should never display the section anchor. The limitation being that manual cross-references to API objects won't show the identifier. We could consider using an additional attribute (other than `optional`) to label cross-refs as "API objects" or not, though users would still have to annotate their manual cross-refs with such an attribute to enjoy the appended identifier to the title. Issue-33: #33 Issue-62: #62
pawamoy
added a commit
that referenced
this issue
Feb 23, 2025
This change adds a `link_titles` option that defaults to `"auto"`. In automatic mode, link titles are either: - always set if Material for MkDocs and its instant preview feature aren't detected - only set on external links otherwise (since instant preview are not supported on external links anyway) The option also accepts the `True` and `False`, for always/never setting titles, respectively. An update to the title logic accompanies this change in order to make use of recorded heading titles (a change brought two commit ago): - optional cross-references will use the original title, and optionally append the identifier if it doesn't already appear in the title - mandatory cross-references will use either the original title if there's one, or no title at all This is because optional cross-refs are almost exclusively created by mkdocstrings handlers, and therefore displaying the identifier (full qualified name of objects) is useful when hovering on a link. Manual cross-references on the other hand can often be references to text sections, and should never display the section anchor. The limitation being that manual cross-references to API objects won't show the identifier. We could consider using an additional attribute (other than `optional`) to label cross-refs as "API objects" or not, though users would still have to annotate their manual cross-refs with such an attribute to enjoy the appended identifier to the title. Issue-33: #33 Issue-62: #62
pawamoy
added a commit
that referenced
this issue
Feb 23, 2025
This change adds a `link_titles` option that defaults to `"auto"`. In automatic mode, link titles are either: - always set if Material for MkDocs and its instant preview feature aren't detected - only set on external links otherwise (since instant preview are not supported on external links anyway) The option also accepts the `True` and `False`, for always/never setting titles, respectively. An update to the title logic accompanies this change in order to make use of recorded heading titles (a change brought two commit ago): - optional cross-references will use the original title, and optionally append the identifier if it doesn't already appear in the title - mandatory cross-references will use either the original title if there's one, or no title at all This is because optional cross-refs are almost exclusively created by mkdocstrings handlers, and therefore displaying the identifier (full qualified name of objects) is useful when hovering on a link. Manual cross-references on the other hand can often be references to text sections, and should never display the section anchor. The limitation being that manual cross-references to API objects won't show the identifier. We could consider using an additional attribute (other than `optional`) to label cross-refs as "API objects" or not, though users would still have to annotate their manual cross-refs with such an attribute to enjoy the appended identifier to the title. Issue-33: #33 Issue-62: #62
|
Will be part of next release. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Is your feature request related to a problem? Please describe.
Material for MkDocs has a nice instant preview feature which displays a modal with the link's contents when hovering on a local link. However it doesn't show the modal if the link has a
titleattribute, instead it shows a simple tooltip. Currently autorefs adds titles when the displayed text is different than the full id, which is very often the case, preventing instant previews to show up.Describe the solution you'd like
Find a way to only add titles to external links (which cannot be instant previewed). For example, we could check that an identifier is not in the URLs maps (primary and secondary), just like we don't register backlinks that are not in these maps.
Additionally, we could maybe set such
titleattributes on headings themselves when they don't show the full path. These tooltips won't show up within instant previews though.Describe alternatives you've considered
Additional context
The text was updated successfully, but these errors were encountered: