Glossary
Render linked definitions from ADT data in WebPub and use EPUB’s native glossary markup when it is available.
WebPub exports keep glossary terms in content/i18n/<lang>/glossary.json. Match each term and its variations in visible text, then open the definition in a keyboard-accessible popover.
content/i18n/en-US/glossary.json{
"body": {
"word": "body",
"definition": "the whole physical person or animal",
"variations": [
"body",
"bodies"
],
"emoji": "🧍🐾",
"id": "gl001"
},
"broken": {
"word": "broken",
"definition": "damaged so that something is not whole or working properly",
"variations": [
"broken",
"break",
"breaks",
"broke"
],
"emoji": "🩹💔",
"id": "gl002"
},
"cloud": {
"word": "cloud",
"definition": "a white or gray shape in the sky made of tiny drops of water",
"variations": [
"cloud",
"clouds"
],
"emoji": "☁️🌥️",
"id": "gl003"
},
// … 17 more entries
}Apply and clean up
Give marked terms a visible affordance, such as a dotted underline. Before applying the glossary again, unwrap existing markers, remove its popover, injected styles, and event listeners. Without explicit teardown, markers nest and handlers stack after navigation or a language switch.
Match only text nodes in the reading content, never existing links, controls, hidden content, or an existing glossary marker. Use locale-aware word segmentation where the language supports it, prefer the longest overlapping variation, and preserve the original text node around each match.
EPUB uses native markup
In an EPUB export, glossary terms are lowered to epub:type="glossref" anchors pointing to glossary.xhtml. Prefer your EPUB engine’s glossary support when it exists. The EPUB does not carry glossary.json in its language folders.
OEBPS/glossary.xhtml<body>
<section epub:type="glossary" role="doc-glossary">
<h1>Glossary</h1>
<dl class="gl-list">
<dt id="gl_001"><dfn style="font-size:24px;font-weight:bold;font-style:normal">body</dfn></dt>
<dd><p style="font-size:24px;line-height:1.4;margin:0.4em 0 0 0"><span class="gl-emoji" aria-hidden="true" style="font-size:24px">🧍🐾 </span>the whole physical person or animal</p>
</dd>
<dt id="gl_002"><dfn style="font-size:24px;font-weight:bold;font-style:normal">broken</dfn></dt>
<dd><p style="font-size:24px;line-height:1.4;margin:0.4em 0 0 0"><span class="gl-emoji" aria-hidden="true" style="font-size:24px">🩹💔 </span>damaged so that something is not whole or working properly</p>
</dd>
<dt id="gl_003"><dfn style="font-size:24px;font-weight:bold;font-style:normal">cloud</dfn></dt>
<dd><p style="font-size:24px;line-height:1.4;margin:0.4em 0 0 0"><span class="gl-emoji" aria-hidden="true" style="font-size:24px">☁️🌥️ </span>a white or gray shape in the sky made of tiny drops of water</p>
</dd>
<dt id="gl_004"><dfn style="font-size:24px;font-weight:bold;font-style:normal">crash</dfn></dt>
<dd><p style="font-size:24px;line-height:1.4;margin:0.4em 0 0 0"><span class="gl-emoji" aria-hidden="true" style="font-size:24px">💥😵 </span>to hit something very hard</p>
</dd>
<dt id="gl_005"><dfn style="font-size:24px;font-weight:bold;font-style:normal">fall</dfn></dt>
<dd><p style="font-size:24px;line-height:1.4;margin:0.4em 0 0 0"><span class="gl-emoji" aria-hidden="true" style="font-size:24px">⬇️😨 </span>to move downward through the air to the ground</p>
</dd>
<dt id="gl_006"><dfn style="font-size:24px;font-weight:bold;font-style:normal">feather</dfn></dt>
<dd><p style="font-size:24px;line-height:1.4;margin:0.4em 0 0 0"><span class="gl-emoji" aria-hidden="true" style="font-size:24px">🪶🐦 </span>one of the soft, light parts that cover a bird's body and wings</p>
</dd>
<dt id="gl_007"><dfn style="font-size:24px;font-weight:bold;font-style:normal">fly</dfn></dt>
<dd><p style="font-size:24px;line-height:1.4;margin:0.4em 0 0 0"><span class="gl-emoji" aria-hidden="true" style="font-size:24px">🪽☁️ </span>to move through the air</p>
</dd>
<dt id="gl_008"><dfn style="font-size:24px;font-weight:bold;font-style:normal">graze</dfn></dt>
<!-- … 41 more lines -->A glossary can be language-specific
The EPUB glossary is generated for the export language. A reader that switches language needs to handle the absence of a matching native glossary gracefully.