Register heading title to add it back as `title` attribute #33

pawamoy · 2023-09-18T15:52:14Z

@waylan noticed that links created by autorefs with the [title][id] syntax do not have a title HTML attribute. It would be nice to have a title in any case:

for object headings, using the object's complete identifier (dotted-path in Python) as title
for text headings, using the actual title

As to how to record these:

mkdocstrings' do_heading filter can probably use the passed id
when picking up the rest of headings, autorefs could register their contents alongside their slugs and URLs

An alternative would be to reuse the provided identifier in [title][id] as title HTML attribute if it is different than the provided title, but that would only make sense for objects, not regular headings (we don't want to show a tooltip on hover with a heading's slug).

The text was updated successfully, but these errors were encountered:

waylan · 2023-09-19T17:51:37Z

I was curious how this plugin worked and see that your reference store is of the format dict[str, str]. However, Python Markdown's store is of the format dict[str, tuple[str, str]] as you can see in markdown/blockprocessors.py#L574 (self.parser.md.references[id] = (link, title)). Presumably, if you did the same, you would know what the source of the reference was when creating it and could more easily determine a title at that time. For example, you would know you were creating a reference for a code object and could generate a title when saving to the store. For that matter, you could even store the label of TOC links as titles.

This change makes autorefs record heading titles alongside URLs, but doesn't actually change the rendering logic. This will be done in a later change that will rely on new title-related options. Issue-33: #33

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

The plugin records heading titles, and sets them as `title` attribute of cross-references (HTML links). Sometimes these titles contain HTML, and some MkDocs themes do not support HTML in them (they are shown as tooltips when hovering on links). This option allows to strip tags (while keeping text) from titles. When set to `"auto"` (default value), it only strips tags for unsupported themes (all except Material for MkDocs). Issue-33: #33