autorefs icon indicating copy to clipboard operation
autorefs copied to clipboard

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

Open pawamoy opened this issue 2 years ago • 1 comments

@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).

pawamoy avatar Sep 18 '23 15:09 pawamoy

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.

waylan avatar Sep 19 '23 17:09 waylan