feat(docs): switch glossary to hover/click/tap popover tooltips

Author: kryptonianson

docs/.vitepress/theme/custom.css

@@ -41,11 +41,12 @@
   --vp-button-brand-active-text: #111111;
 }
 
-/* Tooltips from markdown-it-glossary render as plain <abbr title>. Make them discoverable. */
-abbr[title] {
+/* Glossary terms render as plain <abbr title>. Underline them so they are discoverable;
+   the pointer cursor comes from enableGlossaryTooltips(). Selecting on `abbr` alone, not
+   `abbr[title]`, keeps the underline while a popover is open (the title is lifted then). */
+abbr {
   text-decoration: underline dotted;
   text-underline-offset: 3px;
-  cursor: help;
 }
 
 .vp-doc img {

docs/.vitepress/theme/index.ts

@@ -2,15 +2,15 @@ import DefaultTheme from 'vitepress/theme';
 import type { Theme } from 'vitepress';
 import { registerMarkdownTags } from '@binarynoir/vitepress-markdown-tags/theme';
 import '@binarynoir/vitepress-markdown-tags/style.css';
-import { enableGlossaryTouch } from 'markdown-it-glossary/client';
+import { enableGlossaryTooltips } from 'markdown-it-glossary/client';
 import './custom.css';
 
 export default {
   extends: DefaultTheme,
   enhanceApp({ app }) {
     // Registers the <MarkdownTag> component that ((tag|...)) compiles to.
     registerMarkdownTags(app);
-    // Tap a glossary term to see its definition on touch screens, where hover doesn't exist.
-    enableGlossaryTouch();
+    // Glossary definitions in a popover on hover, click and tap (title tooltips never show on touch screens).
+    enableGlossaryTooltips();
   },
 } satisfies Theme;

docs/plugins/glossary.md

@@ -38,32 +38,33 @@ export default defineConfig({
 
 Or wrap the config with `withGlossary` from `markdown-it-glossary/vitepress`. It plays nicely with other `withX()` wrappers.
 
-### Touch devices
+### Hover, click and tap
 
-`<abbr title>` tooltips only appear on hover, so they never show on a phone or tablet. Call `enableGlossaryTouch()` once in the browser and tapping a term shows its definition in a small popover instead. Tapping elsewhere, scrolling, or pressing Escape dismisses it. It only activates on devices that can't hover, so desktop keeps the native tooltip.
+`<abbr title>` tooltips need a mouse hover, so they never show on a phone or tablet. Call `enableGlossaryTooltips()` once in the browser and every term gets a small popover that works with any input: hover a term with a mouse (click to pin it open), or tap it on a touch screen. Tap the term again, tap elsewhere, scroll, or press Escape to dismiss it. While the popover is open the term's `title` is lifted so the browser's own tooltip doesn't show on top of it, then restored.
 
 In VitePress, call it from your theme's `enhanceApp`:
 
 ```ts
 // .vitepress/theme/index.ts
 import DefaultTheme from 'vitepress/theme';
-import { enableGlossaryTouch } from 'markdown-it-glossary/client';
+import { enableGlossaryTooltips } from 'markdown-it-glossary/client';
 
 export default {
   extends: DefaultTheme,
   enhanceApp() {
-    enableGlossaryTouch();
+    enableGlossaryTooltips();
   },
 };
 ```
 
 | Option         | Default         | Description                                                                    |
 | -------------- | --------------- | ------------------------------------------------------------------------------ |
 | `selector`     | `'abbr[title]'` | Which elements carry a definition in their `title`.                            |
-| `touchOnly`    | `true`          | Only activate on devices that can't hover. `false` also enables it on desktop. |
+| `hover`        | `true`          | Show on mouse hover too. `false` for click and tap only.                       |
+| `touchOnly`    | `false`         | Respond to touch input only, leaving mouse users the native tooltip.           |
 | `injectStyles` | `true`          | Inject the default popover styles. `false` lets you style `.glossary-popover`. |
 
-The default look follows VitePress theme colors and can be overridden with the `--glossary-popover-bg`, `--glossary-popover-fg`, and `--glossary-popover-border` CSS variables. `enableGlossaryTouch()` returns a function that removes its listeners.
+The default look follows VitePress theme colors and can be overridden with the `--glossary-popover-bg`, `--glossary-popover-fg`, and `--glossary-popover-border` CSS variables. `enableGlossaryTooltips()` returns a function that removes its listeners.
 
 ## Writing the glossary file
 
@@ -126,6 +127,6 @@ The same syntax works on a page that has _not_ opted out. A page-local definitio
 | `headingLevel`   | `3`          | Heading level that marks a term.                            |
 | `frontmatterKey` | `'glossary'` | Frontmatter key for the opt-out. `false` disables it.       |
 
-The plugin emits plain `<abbr title>` tags and injects no CSS. This site adds a dotted underline and a help cursor in its theme so the tooltips are discoverable.
+The plugin itself emits plain `<abbr title>` tags and injects no CSS. This site adds a dotted underline in its theme so the terms are discoverable, and `enableGlossaryTooltips()` adds the popover and a pointer cursor.
 
 [Source and full README on GitHub](https://github.com/binarynoir/markdown-it-glossary)

package-lock.json

@@ -28,9 +28,9 @@
     "@binarynoir/vitepress-auto-sidebar": "^0.4.10",
     "@binarynoir/vitepress-downloads": "^0.1.1",
     "@binarynoir/vitepress-markdown-tags": "^0.2.3",
-    "@binarynoir/vitepress-reading-time-tag": "^0.1.4",
+    "@binarynoir/vitepress-reading-time-tag": "^0.1.5",
     "@types/node": "^24.19.1",
-    "markdown-it-glossary": "^0.3.5",
+    "markdown-it-glossary": "^0.3.6",
     "prettier": "^3.9.9",
     "vitepress": "2.0.0-alpha.20"
   }