Skip to content

Commit a31d6fd

Browse files
committed
docs(glossary): document per-page abbr overrides and touch support
1 parent e500666 commit a31d6fd

4 files changed

Lines changed: 60 additions & 6 deletions

File tree

‎docs/.vitepress/theme/index.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,15 @@ import DefaultTheme from 'vitepress/theme';
22
import type { Theme } from 'vitepress';
33
import { registerMarkdownTags } from '@binarynoir/vitepress-markdown-tags/theme';
44
import '@binarynoir/vitepress-markdown-tags/style.css';
5+
import { enableGlossaryTouch } from 'markdown-it-glossary/client';
56
import './custom.css';
67

78
export default {
89
extends: DefaultTheme,
910
enhanceApp({ app }) {
1011
// Registers the <MarkdownTag> component that ((tag|...)) compiles to.
1112
registerMarkdownTags(app);
13+
// Tap a glossary term to see its definition on touch screens, where hover doesn't exist.
14+
enableGlossaryTouch();
1215
},
1316
} satisfies Theme;

‎docs/plugins/glossary.md‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,33 @@ export default defineConfig({
3838

3939
Or wrap the config with `withGlossary` from `markdown-it-glossary/vitepress`. It plays nicely with other `withX()` wrappers.
4040

41+
### Touch devices
42+
43+
`<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.
44+
45+
In VitePress, call it from your theme's `enhanceApp`:
46+
47+
```ts
48+
// .vitepress/theme/index.ts
49+
import DefaultTheme from 'vitepress/theme';
50+
import { enableGlossaryTouch } from 'markdown-it-glossary/client';
51+
52+
export default {
53+
extends: DefaultTheme,
54+
enhanceApp() {
55+
enableGlossaryTouch();
56+
},
57+
};
58+
```
59+
60+
| Option | Default | Description |
61+
| -------------- | --------------- | ------------------------------------------------------------------------------ |
62+
| `selector` | `'abbr[title]'` | Which elements carry a definition in their `title`. |
63+
| `touchOnly` | `true` | Only activate on devices that can't hover. `false` also enables it on desktop. |
64+
| `injectStyles` | `true` | Inject the default popover styles. `false` lets you style `.glossary-popover`. |
65+
66+
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.
67+
4168
## Writing the glossary file
4269

4370
Each term is a `###` heading followed by its definition as the next paragraph. This site's own [glossary file](/reference/glossary) is written like this:
@@ -64,7 +91,31 @@ glossary: false
6491
---
6592
```
6693

67-
The glossary page itself uses this so its headings don't tooltip themselves. To override one term on one page, write a real markdown-it-abbr definition anywhere on that page: `*[CI]: something else`.
94+
The glossary page itself uses this so its headings don't tooltip themselves.
95+
96+
Opting out only turns off the site-wide glossary for that page. The page still supports [markdown-it-abbr](https://github.com/markdown-it/markdown-it-abbr), so you can add tooltips by hand. Write a definition line anywhere in the page's Markdown, in the form `*[Term]: definition`:
97+
98+
```md
99+
---
100+
glossary: false
101+
---
102+
103+
# Release notes
104+
105+
We cut a release every sprint, and each one is gated on CI passing.
106+
107+
*[CI]: Continuous Integration, only this page's definition applies.
108+
```
109+
110+
Every exact, case-sensitive occurrence of `CI` on that page becomes an `<abbr title>`, and nothing else from the glossary does. The definition line itself isn't rendered. Use this to keep a few terms on an otherwise opted-out page, or to define terms that aren't in the glossary at all.
111+
112+
### Override one term on one page
113+
114+
The same syntax works on a page that has _not_ opted out. A page-local definition always wins over the site-wide one for that term, on that page:
115+
116+
```md
117+
*[CI]: something else, on this page only
118+
```
68119

69120
## Options
70121

‎package-lock.json‎

Lines changed: 4 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
"@binarynoir/vitepress-markdown-tags": "^0.2.3",
3131
"@binarynoir/vitepress-reading-time-tag": "^0.1.4",
3232
"@types/node": "^24.19.1",
33-
"markdown-it-glossary": "^0.3.4",
33+
"markdown-it-glossary": "^0.3.5",
3434
"prettier": "^3.9.9",
3535
"vitepress": "2.0.0-alpha.20"
3636
}

0 commit comments

Comments
 (0)