docusaurus-plugin-glossary 1.3.2 → 2.0.1

package/README.md

@@ -1,8 +1,13 @@
 # docusaurus-plugin-glossary
 
+[![npm version](https://img.shields.io/npm/v/docusaurus-plugin-glossary.svg)](https://www.npmjs.com/package/docusaurus-plugin-glossary)
+[![ci](https://github.com/mcclowes/docusaurus-plugin-glossary/actions/workflows/ci.yml/badge.svg)](https://github.com/mcclowes/docusaurus-plugin-glossary/actions/workflows/ci.yml)
+
+![docusaurus-plugin-glossary banner](banner.png)
+
 A comprehensive Docusaurus plugin that provides glossary functionality with an auto-generated glossary page, searchable terms, and inline term tooltips.
 
-> Compatibility: Fully compatible with Docusaurus v3 (MDX v3). If you were on a v2-era fork, please upgrade to the latest 1.x release of this plugin.
+> Compatibility: Fully compatible with Docusaurus v3 (MDX v3). If you were on a v2-era fork, please upgrade to the latest 2.x release of this plugin.
 
 ## Features
 
@@ -246,9 +251,46 @@ module.exports = {
 };
 ```
 
+## How It Works
+
+This plugin uses a **hybrid approach** combining build-time transformation and runtime enhancements, inspired by `docusaurus-plugin-image-zoom`:
+
+### Build-Time: Remark Plugin
+
+The remark plugin automatically detects glossary terms in your markdown and:
+1. Transforms plain text terms into `<GlossaryTerm>` JSX components
+2. Automatically injects the necessary import statement (`import GlossaryTerm from '@theme/GlossaryTerm';`)
+3. This happens during the MDX compilation, before React renders anything
+
+**No manual imports needed!** When you write:
+```markdown
+Our API uses REST principles.
+```
+
+The remark plugin transforms it to:
+```jsx
+import GlossaryTerm from '@theme/GlossaryTerm';
+
+Our <GlossaryTerm term="API">API</GlossaryTerm> uses <GlossaryTerm term="REST">REST</GlossaryTerm> principles.
+```
+
+### Runtime: Client Modules
+
+The plugin uses Docusaurus's `getClientModules()` API to automatically load client-side code on every page. This ensures:
+- Glossary term functionality is available globally without configuration
+- Components initialize correctly on each route change
+- No performance impact from manual module loading
+
+### Theme Components
+
+The `GlossaryTerm` component is provided via the theme system (`@theme/GlossaryTerm`), making it:
+- Available to all MDX files through automatic imports
+- Swizzlable for custom styling and behavior
+- Accessible to both the remark plugin and manual usage
+
 ## Docusaurus v3 Notes and Troubleshooting
 
-- **MDX imports**: The plugin injects `import GlossaryTerm from '@theme/GlossaryTerm';` automatically when it auto-links a term. If you’re writing MDX manually, you can also import and use it yourself:
+- **MDX imports**: The plugin automatically injects `import GlossaryTerm from '@theme/GlossaryTerm';` when it auto-links a term. You can also use it manually in MDX:
 
   ```mdx
   import GlossaryTerm from '@theme/GlossaryTerm';
@@ -261,7 +303,7 @@ module.exports = {
   - Ensure the plugin is listed in `plugins` AND the remark plugin is configured in your preset (see Step 2 above).
   - Visit `/glossary`. If the page or route fails to render, verify your `glossaryPath` file exists and contains a `terms` array.
   - Clear your Docusaurus cache with `npm run clear` and restart your dev server.
-  - If you previously used a local patch for `1.0.0`, remove it when using `1.0.2+`; the plugin bundles the v3-compatible theme and remark integration.
+  - If you previously used an older version (v1.0.x), upgrade to the latest version; the plugin bundles the v3-compatible theme and remark integration.
 
 - **Opting out of auto-linking**: Simply don't configure the remark plugin in your preset. You can still use the `<GlossaryTerm />` component manually where you want explicit control.
 
@@ -454,38 +496,85 @@ principles to provide a simple and consistent interface.
 
 ## Development
 
+This project is written in TypeScript and compiles to JavaScript. The source files are in `src/` and the compiled output goes to `lib/`.
+
 ### File Structure
 
 ```
 docusaurus-plugin-glossary/
-├── index.js                    # Main plugin file
-├── components/
-│   ├── GlossaryPage.js        # Glossary page component
-│   └── GlossaryPage.module.css # Glossary page styles
-├── remark/
-│   └── glossary-terms.js      # Remark plugin for automatic term detection
-├── theme/
-│   └── GlossaryTerm/
-│       ├── index.js           # Term component
-│       └── styles.module.css  # Term styles
-└── README.md
+├── src/
+│   ├── index.ts               # Main plugin entry point (TypeScript)
+│   ├── client/
+│   │   └── index.js           # Client module for runtime initialization
+│   ├── components/
+│   │   ├── GlossaryPage.js    # Glossary page component
+│   │   ├── GlossaryPage.module.css
+│   │   └── GlossaryPage.test.js
+│   ├── remark/
+│   │   └── glossary-terms.js  # Remark plugin for automatic term detection
+│   └── theme/
+│       └── GlossaryTerm/
+│           ├── index.js       # Term component
+│           ├── styles.module.css
+│           └── index.test.js
+├── lib/                       # Compiled output (generated by build)
+│   ├── index.js               # Main plugin file (compiled from src/index.ts)
+│   ├── client/                # Copied from src/client/
+│   ├── components/            # Copied from src/components/
+│   ├── remark/                # Copied from src/remark/
+│   └── theme/                 # Copied from src/theme/
+├── __tests__/
+│   └── plugin.test.js         # Plugin lifecycle tests
+├── examples/
+│   └── docusaurus-v3/         # Example Docusaurus site
+├── scripts/
+│   ├── build.js               # Build script (TypeScript + copy files)
+│   ├── watch.js               # Watch script for development
+│   └── ...
+└── package.json
+```
+
+### Building
+
+The project uses TypeScript for the main plugin entry point (`src/index.ts`) and JavaScript for components. To build:
+
+```bash
+npm run build
+```
+
+This will:
+1. Compile TypeScript (`src/index.ts`) to JavaScript (`lib/index.js`)
+2. Copy JavaScript, CSS, and test files from `src/` to `lib/`
+
+For development, use:
+
+```bash
+npm run watch
 ```
 
+This watches for changes and automatically rebuilds.
+
 ### Plugin Lifecycle
 
-1. **loadContent**: Reads glossary JSON file
-2. **contentLoaded**: Creates data file and adds route
-3. **getThemePath**: Exposes theme components
-4. **getPathsToWatch**: Watches glossary file for changes
+The plugin follows Docusaurus plugin lifecycle hooks:
+
+1. **getClientModules**: Returns client modules that load automatically on every page (provides runtime initialization)
+2. **loadContent**: Reads glossary JSON file from the configured path
+3. **contentLoaded**: Creates data files for components and remark plugin, adds glossary page route
+4. **getThemePath**: Exposes theme components (`GlossaryTerm`)
+5. **getPathsToWatch**: Watches glossary file for changes during development
+6. **postBuild**: Optional post-build hook for additional processing
 
 ### Remark Plugin
 
-The remark plugin (`remark/glossary-terms.js`) automatically detects glossary terms in markdown files and replaces them with `GlossaryTerm` components. It:
+The remark plugin (`remark/glossary-terms.js`) automatically detects glossary terms in markdown files and transforms them at build time. It:
 
 - Scans text nodes for glossary terms (case-insensitive, whole word matching)
-- Replaces matching terms with MDX components that show tooltips
+- Replaces matching terms with `<GlossaryTerm>` MDX components
+- Automatically injects the necessary import statement (`import GlossaryTerm from '@theme/GlossaryTerm';`)
 - Skips terms inside code blocks, links, or existing MDX components
 - Respects word boundaries to avoid partial matches
+- Handles plural forms (e.g., "API" matches "APIs")
 
 ## Troubleshooting
 
@@ -534,3 +623,10 @@ Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md)
 ## Credits
 
 Built for Docusaurus v3.x
+
+## Technical Details
+
+- **Language**: TypeScript (main plugin) + JavaScript (components)
+- **Build System**: TypeScript compiler + custom build scripts
+- **Package Entry Point**: `lib/index.js` (compiled from `src/index.ts`)
+- **Exports**: Main plugin, remark plugin via package.json exports field

package/lib/client/index.js

@@ -0,0 +1,35 @@
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+/**
+ * Client module for glossary plugin
+ * This runs automatically on every page via getClientModules()
+ * Similar to docusaurus-plugin-image-zoom approach
+ */
+export default (function () {
+  // Only run in browser environment
+  if (!ExecutionEnvironment.canUseDOM) {
+    return null;
+  }
+
+  return {
+    onRouteUpdate({ location }) {
+      // GlossaryTerm components handle their own tooltips via React
+      // This client module can handle any global initialization if needed
+
+      // Optional: Log for debugging
+      if (process.env.NODE_ENV !== 'production') {
+        const glossaryTerms = document.querySelectorAll('[data-glossary-term], .glossaryTerm');
+        if (glossaryTerms.length > 0) {
+          console.log(
+            `[glossary-plugin] Initialized ${glossaryTerms.length} glossary term(s) on route:`,
+            location.pathname
+          );
+        }
+      }
+
+      // Future enhancement: Could add DOM-based term detection here
+      // This would find plain text terms and add tooltips without requiring
+      // the remark plugin, similar to how image-zoom finds and enhances <img> tags
+    },
+  };
+})();

package/lib/index.js

@@ -13,48 +13,74 @@ function getDirname() {
         return '';
     }
     // Use cached value if available
-    if (globalThis.__dirnameCache) {
-        return globalThis.__dirnameCache;
+    const global = globalThis;
+    if (global.__dirnameCache) {
+        return global.__dirnameCache;
     }
-    // In Jest/Babel transformed environment, __filename is available
-    // @ts-ignore - __filename is available after Babel transforms ES modules to CommonJS
-    if (typeof __filename !== 'undefined') {
-        const computedDirname = path.dirname(__filename);
-        globalThis.__dirnameCache = computedDirname;
-        return computedDirname;
-    }
-    // Check if import.meta.url is available
-    // Use try-catch to handle cases where import.meta is undefined (e.g., in Jest before transform)
-    let hasImportMetaUrl = false;
-    try {
-        hasImportMetaUrl = typeof import.meta.url !== 'undefined';
-    }
-    catch {
-        // import.meta is undefined (e.g., in Jest environment before Babel transform)
-        return '';
-    }
-    if (!hasImportMetaUrl) {
+    // Use a lock to prevent race conditions when multiple calls happen concurrently
+    // This ensures only one execution path computes and sets the cache
+    if (global.__dirnameComputing) {
+        // Another call is already computing __dirname, wait and retry
+        // In practice, this should be rare since module initialization is typically sequential
+        let retries = 0;
+        while (global.__dirnameComputing && retries < 10) {
+            retries++;
+            // Busy wait with a small delay (not ideal but works for module init)
+        }
+        // Return cached value if available after waiting
+        if (global.__dirnameCache) {
+            return global.__dirnameCache;
+        }
+        // If still computing after retries, return empty to avoid deadlock
         return '';
     }
-    // Try to compute __dirname using fileURLToPath via createRequire
-    // This avoids webpack trying to bundle fileURLToPath at module load time
+    // Set computing flag to prevent concurrent execution
+    global.__dirnameComputing = true;
     try {
-        const require = createRequire(import.meta.url);
-        const urlModule = require('url');
-        // Check if fileURLToPath is actually a function (webpack may provide a broken polyfill)
-        if (urlModule && typeof urlModule.fileURLToPath === 'function') {
-            const __filename = urlModule.fileURLToPath(import.meta.url);
+        // In Jest/Babel transformed environment, __filename is available
+        // @ts-ignore - __filename is available after Babel transforms ES modules to CommonJS
+        if (typeof __filename !== 'undefined') {
             const computedDirname = path.dirname(__filename);
-            globalThis.__dirnameCache = computedDirname;
+            global.__dirnameCache = computedDirname;
             return computedDirname;
         }
-    }
-    catch (error) {
-        // If webpack provides a broken polyfill or require fails, return empty
-        // __dirname will be computed when the plugin function is called (server-side only)
+        // Check if import.meta.url is available
+        // Use try-catch to handle cases where import.meta is undefined (e.g., in Jest before transform)
+        let hasImportMetaUrl = false;
+        try {
+            hasImportMetaUrl = typeof import.meta.url !== 'undefined';
+        }
+        catch {
+            // import.meta is undefined (e.g., in Jest environment before Babel transform)
+            return '';
+        }
+        if (!hasImportMetaUrl) {
+            return '';
+        }
+        // Try to compute __dirname using fileURLToPath via createRequire
+        // This avoids webpack trying to bundle fileURLToPath at module load time
+        try {
+            const require = createRequire(import.meta.url);
+            const urlModule = require('url');
+            // Check if fileURLToPath is actually a function (webpack may provide a broken polyfill)
+            if (urlModule && typeof urlModule.fileURLToPath === 'function') {
+                const __filename = urlModule.fileURLToPath(import.meta.url);
+                const computedDirname = path.dirname(__filename);
+                global.__dirnameCache = computedDirname;
+                return computedDirname;
+            }
+        }
+        catch (error) {
+            // If webpack provides a broken polyfill or require fails, return empty
+            // __dirname will be computed when the plugin function is called (server-side only)
+            return '';
+        }
         return '';
     }
-    return '';
+    finally {
+        // Always clear the computing flag
+        global.__dirnameComputing = false;
+    }
 }
 // Initialize __dirname at module load time, but handle webpack bundling gracefully
 let __dirname = '';
@@ -62,33 +88,51 @@ let peerDepsValidated = false;
 try {
     // Only compute __dirname if we're in Node.js (not during webpack bundling)
     if (typeof process !== 'undefined' && ((_a = process.versions) === null || _a === void 0 ? void 0 : _a.node)) {
-        // In Jest/Babel transformed environment, __filename is available
-        // @ts-ignore - __filename is available after Babel transforms ES modules to CommonJS
-        if (typeof __filename !== 'undefined') {
-            __dirname = path.dirname(__filename);
-            validatePeerDependencies(__dirname);
-            peerDepsValidated = true;
-        }
-        else {
-            // Check if import.meta.url is available - use try-catch since import.meta might be undefined
-            let hasImportMetaUrl = false;
+        const global = globalThis;
+        // Set lock to prevent concurrent getDirname() calls during module init
+        if (!global.__dirnameComputing) {
+            global.__dirnameComputing = true;
             try {
-                hasImportMetaUrl = typeof import.meta.url !== 'undefined';
-            }
-            catch {
-                // import.meta is undefined (e.g., in Jest environment before Babel transform)
-                hasImportMetaUrl = false;
-            }
-            if (hasImportMetaUrl) {
-                const require = createRequire(import.meta.url);
-                const urlModule = require('url');
-                // Check if fileURLToPath is actually a function (not a webpack polyfill)
-                if (urlModule && typeof urlModule.fileURLToPath === 'function') {
-                    const __filename = urlModule.fileURLToPath(import.meta.url);
+                // In Jest/Babel transformed environment, __filename is available
+                // @ts-ignore - __filename is available after Babel transforms ES modules to CommonJS
+                if (typeof __filename !== 'undefined') {
                     __dirname = path.dirname(__filename);
+                    global.__dirnameCache = __dirname;
                     validatePeerDependencies(__dirname);
                     peerDepsValidated = true;
                 }
+                else {
+                    // Check if import.meta.url is available - use try-catch since import.meta might be undefined
+                    let hasImportMetaUrl = false;
+                    try {
+                        hasImportMetaUrl = typeof import.meta.url !== 'undefined';
+                    }
+                    catch {
+                        // import.meta is undefined (e.g., in Jest environment before Babel transform)
+                        hasImportMetaUrl = false;
+                    }
+                    if (hasImportMetaUrl) {
+                        const require = createRequire(import.meta.url);
+                        const urlModule = require('url');
+                        // Check if fileURLToPath is actually a function (not a webpack polyfill)
+                        if (urlModule && typeof urlModule.fileURLToPath === 'function') {
+                            const __filename = urlModule.fileURLToPath(import.meta.url);
+                            __dirname = path.dirname(__filename);
+                            global.__dirnameCache = __dirname;
+                            validatePeerDependencies(__dirname);
+                            peerDepsValidated = true;
+                        }
+                    }
+                }
+            }
+            finally {
+                global.__dirnameComputing = false;
+            }
+        }
+        else {
+            // Another module init is already computing, use cached value if available
+            if (global.__dirnameCache) {
+                __dirname = global.__dirnameCache;
             }
         }
     }
@@ -115,15 +159,33 @@ if (!peerDepsValidated && typeof process !== 'undefined' && ((_b = process.versi
  *
  * A plugin that provides glossary functionality with:
  * - Glossary terms defined in a JSON file
- * - Auto-generated glossary page
- * - GlossaryTerm component for inline definitions
- * - Tooltips on hover
- * - Automatic glossary term detection in markdown files (requires manual remark plugin configuration)
+ * - Auto-generated glossary page with term definitions
+ * - GlossaryTerm component for inline definitions with interactive tooltips
+ * - Automatic client-side initialization via getClientModules() (no manual imports needed)
+ * - Optional automatic glossary term detection in markdown files via remark plugin
+ *
+ * ## Basic Usage (Manual Term Markup)
+ *
+ * Just install the plugin - the GlossaryTerm component is automatically available:
+ * ```javascript
+ * module.exports = {
+ *   plugins: [
+ *     ['docusaurus-plugin-glossary', {
+ *       glossaryPath: 'glossary/glossary.json',
+ *       routePath: '/glossary',
+ *     }],
+ *   ],
+ * };
+ * ```
+ *
+ * Then use `<GlossaryTerm>` in your MDX files without importing:
+ * ```mdx
+ * <GlossaryTerm term="API">API</GlossaryTerm>
+ * ```
  *
- * IMPORTANT: To enable auto-linking of glossary terms, you must manually add the remark plugin
- * to your docusaurus.config.js using the getRemarkPlugin helper:
+ * ## Advanced Usage (Automatic Term Detection)
  *
- * Example:
+ * To automatically detect and link glossary terms in markdown, add the remark plugin:
  * ```javascript
  * const glossaryPlugin = require('docusaurus-plugin-glossary');
  *
@@ -138,14 +200,6 @@ if (!peerDepsValidated && typeof process !== 'undefined' && ((_b = process.versi
  *           }, { siteDir: __dirname }),
  *         ],
  *       },
- *       pages: {
- *         remarkPlugins: [
- *           glossaryPlugin.getRemarkPlugin({
- *             glossaryPath: 'glossary/glossary.json',
- *             routePath: '/glossary',
- *           }, { siteDir: __dirname }),
- *         ],
- *       },
  *     }],
  *   ],
  *   plugins: [
@@ -169,6 +223,11 @@ export default function glossaryPlugin(context, options = {}) {
     let glossaryDataCache = { terms: [] };
     return {
         name: 'docusaurus-plugin-glossary',
+        getClientModules() {
+            // Compute __dirname if not already set (for webpack bundling compatibility)
+            const pluginDirname = __dirname || getDirname();
+            return [path.resolve(pluginDirname, './client/index.js')];
+        },
         async loadContent() {
             // Load glossary terms from JSON file
             const glossaryFilePath = path.resolve(context.siteDir, glossaryPath);
@@ -224,6 +283,8 @@ export default function glossaryPlugin(context, options = {}) {
 }
 // Export remark plugin factory for use in markdown configuration
 export const remarkPlugin = remarkGlossaryTerms;
+// Export cache clearing utility
+export { clearGlossaryCache } from './remark/glossary-terms.js';
 /**
  * Helper function to get the configured remark plugin
  * This can be used in docusaurus.config.js markdown configuration

package/lib/remark/glossary-terms.js

@@ -2,9 +2,18 @@ import { visit } from 'unist-util-visit';
 import path from 'path';
 import fs from 'fs';
 
+// Cache for glossary data to avoid repeated synchronous file reads
+// Key: absolute file path, Value: { terms, loadedAt }
+const glossaryCache = new Map();
+const CACHE_TTL = 5000; // 5 seconds TTL to allow for file changes during dev
+
 /**
  * Creates a remark plugin that automatically detects and replaces glossary terms in markdown
  *
+ * This plugin transforms plain text terms into <GlossaryTerm> JSX elements.
+ * The GlossaryTerm component is globally available via the MDXComponents theme wrapper,
+ * so no import injection is needed - MDX files can use it without explicit imports.
+ *
  * @param {object} options - Plugin options
  * @param {Array} options.terms - Array of glossary term objects with {term, definition}
  * @param {string} options.glossaryPath - Path to glossary JSON file (optional, if terms not provided)
@@ -20,16 +29,56 @@ export default function remarkGlossaryTerms({
 } = {}) {
   let glossaryTerms = terms;
 
-  // If terms not provided, try to load from glossaryPath (synchronously)
+  // If terms not provided, try to load from glossaryPath with caching
   if (!glossaryTerms.length && glossaryPath && siteDir) {
     try {
       const glossaryFilePath = path.resolve(siteDir, glossaryPath);
-      if (fs.existsSync(glossaryFilePath)) {
-        const glossaryData = JSON.parse(fs.readFileSync(glossaryFilePath, 'utf8'));
-        glossaryTerms = glossaryData.terms || [];
+      const now = Date.now();
+
+      // Check cache first to avoid repeated file reads
+      const cached = glossaryCache.get(glossaryFilePath);
+      if (cached && (now - cached.loadedAt) < CACHE_TTL) {
+        glossaryTerms = cached.terms;
+      } else {
+        // Cache miss or expired - load from file synchronously
+        // Note: This is synchronous I/O which can block the build process
+        // Consider passing terms directly to avoid this
+        if (fs.existsSync(glossaryFilePath)) {
+          const fileContent = fs.readFileSync(glossaryFilePath, 'utf8');
+          const glossaryData = JSON.parse(fileContent);
+          glossaryTerms = glossaryData.terms || [];
+
+          // Update cache
+          glossaryCache.set(glossaryFilePath, {
+            terms: glossaryTerms,
+            loadedAt: now,
+          });
+
+          // Log only once per file (when cache is first populated)
+          if (!cached && process.env.NODE_ENV !== 'production') {
+            console.log(`[glossary-plugin] Loaded ${glossaryTerms.length} terms from ${glossaryPath}`);
+          }
+        } else {
+          // File doesn't exist - cache empty result to avoid repeated checks
+          glossaryCache.set(glossaryFilePath, {
+            terms: [],
+            loadedAt: now,
+          });
+          if (process.env.NODE_ENV !== 'production') {
+            console.warn(`[glossary-plugin] Glossary file not found: ${glossaryPath}`);
+          }
+        }
       }
     } catch (error) {
-      console.warn(`Failed to load glossary from ${glossaryPath}:`, error.message);
+      console.warn(`[glossary-plugin] Failed to load glossary from ${glossaryPath}:`, error.message);
+      // Cache the error to avoid repeated attempts
+      if (glossaryPath && siteDir) {
+        const glossaryFilePath = path.resolve(siteDir, glossaryPath);
+        glossaryCache.set(glossaryFilePath, {
+          terms: [],
+          loadedAt: Date.now(),
+        });
+      }
     }
   }
 
@@ -186,7 +235,8 @@ export default function remarkGlossaryTerms({
     return result.length > 0 ? result : [{ type: 'text', value: text }];
   }
 
-  return tree => {
+  // Return the transformer function
+  const transformer = tree => {
     let usedGlossaryTerm = false;
     visit(tree, 'text', (node, index, parent) => {
       // Skip text nodes inside code blocks, links, or existing MDX components
@@ -213,6 +263,7 @@ export default function remarkGlossaryTerms({
           if (replacement.type === 'mdxJsxFlowElement') {
             // In paragraph context, we need mdxJsxTextElement instead
             if (parent.type === 'paragraph') {
+              usedGlossaryTerm = true;
               return {
                 type: 'mdxJsxTextElement',
                 name: replacement.name,
@@ -220,11 +271,6 @@ export default function remarkGlossaryTerms({
                 children: replacement.children,
               };
             }
-          }
-          if (
-            replacement.type === 'mdxJsxFlowElement' ||
-            replacement.type === 'mdxJsxTextElement'
-          ) {
             usedGlossaryTerm = true;
           }
           return replacement;
@@ -236,13 +282,12 @@ export default function remarkGlossaryTerms({
       }
     });
 
-    // Inject MDX import for GlossaryTerm if we used it anywhere in this file
+    // Inject MDX import for GlossaryTerm if we used it
+    // The component is available via theme path, so we just need to import it
     if (usedGlossaryTerm) {
-      // Create import node matching MDX v3 expectations
-      // Both 'value' (the import string) and 'data.estree' (the parsed AST) are required
       const importNode = {
         type: 'mdxjsEsm',
-        value: "import GlossaryTerm from '@theme/GlossaryTerm'",
+        value: 'import GlossaryTerm from "@theme/GlossaryTerm";',
         data: {
           estree: {
             type: 'Program',
@@ -259,7 +304,7 @@ export default function remarkGlossaryTerms({
                 source: {
                   type: 'Literal',
                   value: '@theme/GlossaryTerm',
-                  raw: "'@theme/GlossaryTerm'",
+                  raw: '"@theme/GlossaryTerm"',
                 },
               },
             ],
@@ -267,38 +312,44 @@ export default function remarkGlossaryTerms({
         },
       };
 
-      // Avoid duplicate imports if already present
-      const hasExistingImport =
+      // Check for existing import
+      const hasImport =
         Array.isArray(tree.children) &&
-        tree.children.some(n => {
-          if (n.type !== 'mdxjsEsm') return false;
-          // Check value string (for older MDX format)
-          if (typeof n.value === 'string' && n.value.includes('@theme/GlossaryTerm')) {
-            return true;
-          }
-          // Check estree data (for newer MDX format)
-          if (n.data?.estree?.body) {
-            return n.data.estree.body.some(
-              stmt =>
-                stmt.type === 'ImportDeclaration' && stmt.source?.value === '@theme/GlossaryTerm'
-            );
-          }
-          return false;
-        });
+        tree.children.some(n =>
+          n.type === 'mdxjsEsm' &&
+          (n.value?.includes('@theme/GlossaryTerm') ||
+            n.data?.estree?.body?.some(s => s.source?.value === '@theme/GlossaryTerm'))
+        );
 
-      if (!hasExistingImport) {
-        // Place import at the very beginning of the file (before all other nodes)
-        // This ensures it's available when MDX compiles the JSX elements
-        if (!Array.isArray(tree.children)) {
-          tree.children = [];
-        }
-        // Insert at the very beginning (index 0) to ensure it's processed first
-        tree.children.unshift(importNode);
-        // Debug: verify import was added (remove in production)
-        if (process.env.NODE_ENV !== 'production') {
-          console.log('[glossary-plugin] Injected GlossaryTerm import');
+      if (!hasImport) {
+        if (!Array.isArray(tree.children)) tree.children = [];
+        let insertIndex = 0;
+        for (let i = 0; i < tree.children.length; i++) {
+          const node = tree.children[i];
+          if (node.type === 'yaml' || node.type === 'toml') {
+            insertIndex = i + 1;
+          } else {
+            break;
+          }
         }
+        tree.children.splice(insertIndex, 0, importNode);
       }
     }
   };
+
+  return transformer;
+}
+
+/**
+ * Clears the glossary cache
+ * Useful for testing or when you want to force a reload of glossary data
+ *
+ * @param {string} [filePath] - Optional specific file path to clear. If not provided, clears entire cache.
+ */
+export function clearGlossaryCache(filePath) {
+  if (filePath) {
+    glossaryCache.delete(filePath);
+  } else {
+    glossaryCache.clear();
+  }
 }

package/lib/theme/GlossaryTerm/index.js

@@ -122,7 +122,7 @@ export default function GlossaryTerm({ term, definition, routePath = '/glossary'
               : undefined
           }
         >
-          <strong>{term}:</strong> {effectiveDefinition}
+          <strong>{term}</strong> {effectiveDefinition}
         </span>
       )}
     </span>

package/lib/theme/GlossaryTerm/index.test.js

@@ -34,7 +34,7 @@ describe('GlossaryTerm', () => {
     const tooltip = screen.getByRole('tooltip');
     expect(tooltip).toBeInTheDocument();
     expect(tooltip).toHaveClass('tooltipVisible');
-    expect(tooltip).toHaveTextContent('API: Application Programming Interface');
+    expect(tooltip).toHaveTextContent('API Application Programming Interface');
   });
 
   it('should hide tooltip on mouse leave', async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-glossary",
-  "version": "1.3.2",
+  "version": "2.0.1",
   "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
   "type": "module",
   "main": "lib/index.js",
@@ -23,7 +23,7 @@
   ],
   "scripts": {
     "build": "tsc && node scripts/build.js",
-    "watch": "node scripts/watch.js",
+    "watch": "tsc && node scripts/watch.js",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",