Skip to content

Conversation

@svekars
Copy link

@svekars svekars commented Dec 16, 2025

RE: #32

Problem

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::

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

When hovering over "Custom Operation" on test-page.html, clicking "Compound Operation" in the tooltip navigates to test-page.html#term-Compound-Operation (broken) instead of glossary.html#term-Compound-Operation (correct).

Solution

This PR adds a new configuration option tippy_glossary_base_url that allows users to specify the base URL for glossary term links within tooltips.

Usage:

# conf.py
tippy_glossary_base_url = "glossary.html"

When configured, all #term-* anchor links inside tooltip content are rewritten to include the glossary base URL (e.g., #term-Something → glossary.html#term-Something).

Testing

  • All existing tests pass
  • Added 5 new unit tests covering:
    • Empty base URL (no rewriting)
    • Base URL with glossary term links (correct rewriting)
    • Preservation of non-glossary links
    • Multiple glossary terms in same content
    • Configuration value propagation
  • Manually tested with a real documentation set containing cross-referenced glossary terms

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants