Fix unintended highlighting of certain glossary terms

package.json

@@ -42,6 +42,7 @@
         "husky": "^9.1.7",
         "lint-staged": "^17.0.8",
         "prettier": "^3.8.4",
+        "mdast-util-mdx-jsx": "^3.2.0",
         "prettier-plugin-astro": "^0.14.1",
         "prettier-plugin-sentences-per-line": "^0.2.3",
         "remark-cli": "^12.0.1",

src/components/Glossary.astro

@@ -21,9 +21,7 @@ const definition =
     slotContent?.trim() || glossaryEntry?.definition || 'Definition not found';
 ---
 
-<span class="glossary-term" data-tooltip={definition}>
-    {term}
-</span>
+<span class="glossary-term" data-tooltip={definition}>{term.trim()}</span>
 
 <style>
     .glossary-term {

src/data/glossary.ts

@@ -6,16 +6,27 @@
  *
  * Definitions should not have a period at the end
  *
- * Format:
- * {
- *   term: "TERM",           // The word/abbreviation to match (case-insensitive)
- *   definition: "..."       // The explanation shown on hover
- * }
+ *   @property definition: The explanation shown on hover
+ *   @property caseSensitive: If true, match this term only in its exact casing (e.g. "CAN" won't match "can"). Defaults to false.
+ *   @property term: The word/abbreviation to match (case-insensitive unless caseSensitive is true)
  */
 
 export interface GlossaryTerm {
+    /**
+     * The word/abbreviation to match (case-insensitive)
+     * @example "SystemCore"
+     */
     term: string;
+    /**
+     * The explanation shown on hover
+     * @example "Main processor for robot code, contains various IO"
+     */
     definition: string;
+    /**
+     * If true, match this term only in its exact casing (e.g. "CAN" won't match "can").
+     * @default false
+     */
+    caseSensitive?: boolean;
 }
 
 export const glossaryTerms: GlossaryTerm[] = [
@@ -40,6 +51,7 @@ export const glossaryTerms: GlossaryTerm[] = [
         term: 'CAN',
         definition:
             'Controller Area Network: typically yellow and green cable used to communicate with motor controllers and sensors, can be run in various topographies instead of each cable needing to connect to SystemCore',
+        caseSensitive: true,
     },
     {
         term: 'PWM',

src/plugins/remark-glossary.ts

@@ -1,20 +1,23 @@
-import { visit } from 'unist-util-visit';
-import type { Root, Text } from 'mdast';
+import { visit, SKIP } from 'unist-util-visit';
+import type { Root, RootContent, Text } from 'mdast';
 import type { VFile } from 'vfile';
+import type { MdxJsxTextElement } from 'mdast-util-mdx-jsx';
+
 import { glossaryTerms } from '../data/glossary';
 
 const sortedTerms = [...glossaryTerms].sort(
     (a, b) => b.term.length - a.term.length,
 );
 
-const termMap = new Map<string, string>();
-glossaryTerms.forEach(({ term, definition }) => {
-    termMap.set(term.toLowerCase(), definition);
-});
-
 const pattern = new RegExp(
-    `\\b(${sortedTerms.map((t) => escapeRegex(t.term)).join('|')})\\b`,
-    'gi',
+    `(?<![\\p{L}\\p{N}_])(${sortedTerms
+        .map((t) =>
+            t.caseSensitive
+                ? `(?-i:${escapeRegex(t.term)})`
+                : escapeRegex(t.term),
+        )
+        .join('|')})(?![\\p{L}\\p{N}_])`,
+    'giu',
 );
 
 function escapeRegex(str: string): string {
@@ -28,17 +31,7 @@ export function remarkGlossary() {
         visit(tree, 'text', (node: Text, index, parent) => {
             if (!parent || index === undefined) return;
 
-            if (
-                parent.type === 'link' ||
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                (parent as any).type === 'code' ||
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                (parent as any).type === 'inlineCode' ||
-                (parent as unknown as { tagName?: string }).tagName ===
-                    'abbr' ||
-                (parent as unknown as { tagName?: string }).tagName === 'a' ||
-                (parent as unknown as { tagName?: string }).tagName === 'code'
-            ) {
+            if (parent.type === 'link' || parent.type === 'mdxJsxTextElement') {
                 return;
             }
 
@@ -47,15 +40,13 @@ export function remarkGlossary() {
 
             if (matches.length === 0) return;
 
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const newNodes: any[] = [];
+            const newNodes: RootContent[] = [];
             let lastIndex = 0;
 
             matches.forEach((match) => {
-                const matchStart = match.index!;
+                const matchStart = match.index;
                 const matchEnd = matchStart + match[0].length;
                 const matchedTerm = match[0];
-                const definition = termMap.get(matchedTerm.toLowerCase());
 
                 if (matchStart > lastIndex) {
                     newNodes.push({
@@ -64,10 +55,19 @@ export function remarkGlossary() {
                     });
                 }
 
-                newNodes.push({
-                    type: 'html',
-                    value: `<abbr class="glossary-term" data-tooltip="${escapeHtml(definition || '')}">${escapeHtml(matchedTerm)}</abbr>`,
-                });
+                const glossaryNode: MdxJsxTextElement = {
+                    type: 'mdxJsxTextElement',
+                    name: 'Glossary',
+                    attributes: [
+                        {
+                            type: 'mdxJsxAttribute',
+                            name: 'term',
+                            value: matchedTerm,
+                        },
+                    ],
+                    children: [],
+                };
+                newNodes.push(glossaryNode);
 
                 lastIndex = matchEnd;
             });
@@ -80,17 +80,9 @@ export function remarkGlossary() {
             }
 
             parent.children.splice(index, 1, ...newNodes);
+            return [SKIP, index + newNodes.length];
         });
     };
 }
 
-function escapeHtml(str: string): string {
-    return str
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-}
-
 export default remarkGlossary;

src/plugins/remark-mdx-global-imports.ts

@@ -26,6 +26,7 @@ const GLOBAL_IMPORTS = [
     { name: 'Aside', path: '@components/Aside.astro' },
     { name: 'Slides', path: '@components/Slides.astro' },
     { name: 'LinkButton', path: '@components/LinkButton.astro' },
+    { name: 'Glossary', path: '@components/Glossary.astro' },
     //   { name: 'ImageTable',    path: '@components/ImageTable.astro' },
 ];
 

src/styles/global.css

@@ -288,72 +288,8 @@ aside.sidebar {
    Glossary Terms
    ========================================================================== */
 
-abbr.glossary-term {
-    text-decoration: underline;
-    text-decoration-style: dotted;
-    text-decoration-color: var(--sl-color-gray-4);
-    text-underline-offset: 0.2em;
-    cursor: help;
-    position: relative;
-}
-
-abbr.glossary-term:hover {
-    text-decoration-color: var(--sl-color-gray-2);
-}
-
-abbr.glossary-term::after {
-    content: attr(data-tooltip);
-    position: absolute;
-    bottom: 100%;
-    left: 50%;
-    transform: translateX(-50%);
-    padding: 0.5rem 0.75rem;
-    background: var(--sl-color-gray-6);
-    border: 1px solid var(--sl-color-gray-5);
-    border-radius: 0.375rem;
-    color: var(--sl-color-gray-1);
-    font-size: 0.875rem;
-    line-height: 1.4;
-    white-space: normal;
-    width: max-content;
-    max-width: 300px;
-    text-align: center;
-    z-index: 1000;
-    opacity: 0;
-    visibility: hidden;
-    transition:
-        opacity 0.15s ease,
-        visibility 0.15s ease;
-    pointer-events: none;
-    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
-    margin-bottom: 0.5rem;
-}
-
-abbr.glossary-term:hover::after {
-    opacity: 1;
-    visibility: visible;
-}
-
-abbr.glossary-term::before {
-    content: '';
-    position: absolute;
-    bottom: 100%;
-    left: 50%;
-    transform: translateX(-50%);
-    border: 6px solid transparent;
-    border-top-color: var(--sl-color-gray-5);
-    margin-bottom: -0.25rem;
-    z-index: 1001;
-    opacity: 0;
-    visibility: hidden;
-    transition:
-        opacity 0.15s ease,
-        visibility 0.15s ease;
-}
-
-abbr.glossary-term:hover::before {
-    opacity: 1;
-    visibility: visible;
+.main-pane {
+    isolation: auto !important; /* Ensure glossary popovers are not clipped by parent containers */
 }
 
 /* ==========================================================================