docutils-users

[Docutils-users] Adding a title attribute of reference in custom role

[Wojciech M. <woj...@po...>]

Hi all!

I'm extending docutils to have shorter link. For example: :enwiki:`Docutils`
expands into '<a href="https://en.wikipedia.org/Docutils>Docutils</a>'.
I do that by using method `reference()`, like this:

def enwiki_link_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
    set_classes(options)
    ref, text = wikilink(text, 'en') # implementation detail
    return [nodes.reference(rawtext, nodes.unescape(text), refuri=ref, **options)], []

I want to add a title attribute, like '<a href=".." title="English Wikipedia on Docutils">...</a>'.
Can't figure out how to do this, is it even possible?

Thanks!
I'm not a subscriber, please CC me.

regards
Wojciech

Re: [Docutils-users] Adding a title attribute of reference in custom role

[Guenter M. <mi...@us...>]

Dear Wojciech,

On 2024-12-23, Wojciech Muła via Docutils-users wrote:

> I'm extending docutils to have shorter link. For example: :enwiki:`Docutils`
> expands into '<a href="https://en.wikipedia.org/Docutils>Docutils</a>'.
> I do that by using method `reference()`, like this:

> def enwiki_link_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
>     set_classes(options)
>     ref, text = wikilink(text, 'en') # implementation detail
>     return [nodes.reference(rawtext, nodes.unescape(text), refuri=ref, **options)], []

> I want to add a title attribute, like '<a href=".." title="English
> Wikipedia on Docutils">...</a>'. Can't figure out how to do this, is it
> even possible?

In the `Docutils Document Format`__ (DocTree), the `"title" attribute`__
is only supported for the root element (<document>).

To get a HTML <a> element with a title, you would need to work around this
restriction:

* use "raw" HTML (https://docutils.sourceforge.io/docs/ref/doctree.html#raw)

* use a custom HTML writer that is able to write a "title" attribute for a
  <reference> DocTree element with either
  
  - a non-standard "title" attribute, or
  - a "special" class value (like "title-English-Wikipedia-on-Docutils")
  

Günter


__ https://docutils.sourceforge.io/docs/ref/docutils.dtd

https://docutils.sourceforge.io/docs/ref/doctree.html#title-1