Skip to content

Broken links in the tooltip when using :term: references within glossary term definitions #32

@svekars

Description

@svekars

When using sphinx-tippy for glossary tooltips, any :term: references within a glossary term definition create broken links. This happens because the tooltip content uses relative URLs (e.g., #term-Custom-Operation) which resolve relative to the current page instead of the glossary page.

Example:

  • glossary.rst:
.. glossary::

   Custom Operation
      An Operation defined by users, usually a :term:`Compound Operation`.

   Compound Operation
      A Compound Operation is composed of other operations.
  • test-page.rst:
This page uses a {term}`Custom Operation` reference.

Expected Behavior

When hovering over "Custom Operation" on test-page.html, the tooltip shows the definition. Clicking "Compound Operation" link inside the tooltip should navigate to:

glossary.html#term-Compound-Operation

Actual Behavior

The link in the tooltip resolves to: test-page.html#term-Compound-Operation
This results in a 404 or incorrect navigation because the anchor #term-Compound-Operation doesn't exist on test-page.html.

Possible Solutions

  1. Rewrite relative URLs in tooltip content - When generating tooltip HTML, convert relative #term-* anchors to absolute paths pointing to the glossary page
  2. Add a configuration option - Allow users to specify the base URL for glossary term links in tooltips (e.g., tippy_glossary_base_url = "glossary.html")
  3. Document the limitation - At minimum, document that :term: references should not be used within glossary definitions when using sphinx-tippy

Environment

  • sphinx-tippy version: 0.4.3
  • Sphinx version: 7.x

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions