docusaurus-plugin-glossary 1.0.2 → 1.1.2

package/README.md

@@ -2,6 +2,8 @@
 
 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. No manual MDX pipeline wiring is required when `autoLinkTerms` is enabled (default).
+
 ## Features
 
 - **Auto-generated Glossary Page**: Displays all terms alphabetically with letter navigation
@@ -38,7 +40,7 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
    };
    ```
    
-   **That's it!** The remark plugin is automatically configured - no manual `markdown.remarkPlugins` setup needed.
+   **That’s it!** On Docusaurus v3, the remark plugin is automatically configured via the plugin’s `configureMarkdown` hook — no manual `markdown.remarkPlugins` setup needed.
 
 3. **Create your glossary file at `glossary/glossary.json`:**
    ```json
@@ -168,6 +170,24 @@ module.exports = {
 };
 ```
 
+## 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
+  import GlossaryTerm from '@theme/GlossaryTerm';
+  
+  Our <GlossaryTerm term="API" /> uses <GlossaryTerm term="REST">RESTful</GlossaryTerm> principles.
+  ```
+
+- **No tooltips or no auto-linking?**
+  - Confirm you’re on `@docusaurus/core@^3` and `react@^18`.
+  - Ensure the plugin is listed in `plugins` and `autoLinkTerms` is not disabled.
+  - Visit `/glossary`. If the page or route fails to render, verify your `glossaryPath` file exists and contains a `terms` array.
+  - 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.
+
+- **Opting out of auto-linking**: set `autoLinkTerms: false` and add the remark plugin manually (see above), or only use the `<GlossaryTerm />` component where you want explicit control.
+
 ### Step 3: Use Glossary Terms in Your Content
 
 #### Option A: Automatic Detection (Recommended)

package/index.js

@@ -81,7 +81,7 @@ function glossaryPlugin(context, options = {}) {
     },
 
     async contentLoaded({ content, actions }) {
-      const { createData, addRoute } = actions;
+      const { createData, addRoute, setGlobalData } = actions;
 
       // Create data file that can be imported by components
       const glossaryDataPath = await createData('glossary-data.json', JSON.stringify(content));
@@ -104,6 +104,12 @@ function glossaryPlugin(context, options = {}) {
           glossaryData: glossaryDataPath,
         },
       });
+
+      // Expose global data for runtime lookups (used by GlossaryTerm)
+      setGlobalData({
+        terms: content.terms || [],
+        routePath,
+      });
     },
 
     getThemePath() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-glossary",
-  "version": "1.0.2",
+  "version": "1.1.2",
   "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
   "main": "index.js",
   "files": [
@@ -15,6 +15,9 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "example:start": "npm --prefix examples/docusaurus-v3 run start",
+    "example:build": "npm --prefix examples/docusaurus-v3 run build",
+    "example:serve": "npm --prefix examples/docusaurus-v3 run serve",
     "prepublishOnly": "npm test",
     "version": "npm version",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\"",

package/remark/glossary-terms.js

@@ -168,6 +168,7 @@ function remarkGlossaryTerms({
   }
 
   return (tree) => {
+    let usedGlossaryTerm = false;
     visit(tree, 'text', (node, index, parent) => {
       // Skip text nodes inside code blocks, links, or existing MDX components
       if (
@@ -199,6 +200,12 @@ function remarkGlossaryTerms({
               };
             }
           }
+          if (
+            replacement.type === 'mdxJsxFlowElement' ||
+            replacement.type === 'mdxJsxTextElement'
+          ) {
+            usedGlossaryTerm = true;
+          }
           return replacement;
         });
 
@@ -207,6 +214,40 @@ function remarkGlossaryTerms({
         return index + newNodes.length - 1; // Return new index to continue
       }
     });
+
+    // Inject MDX import for GlossaryTerm if we used it anywhere in this file
+    if (usedGlossaryTerm) {
+      const importNode = {
+        type: 'mdxjsEsm',
+        value: "import GlossaryTerm from '@theme/GlossaryTerm';",
+        data: {
+          estree: {
+            type: 'Program',
+            sourceType: 'module',
+            body: [
+              {
+                type: 'ImportDeclaration',
+                specifiers: [
+                  {
+                    type: 'ImportDefaultSpecifier',
+                    local: { type: 'Identifier', name: 'GlossaryTerm' }
+                  }
+                ],
+                source: { type: 'Literal', value: '@theme/GlossaryTerm' }
+              }
+            ]
+          }
+        }
+      };
+
+      // Avoid duplicate imports if already present
+      const hasExistingImport = Array.isArray(tree.children) && tree.children.some(
+        (n) => n.type === 'mdxjsEsm' && typeof n.value === 'string' && n.value.includes("@theme/GlossaryTerm")
+      );
+      if (!hasExistingImport) {
+        tree.children.unshift(importNode);
+      }
+    }
   };
 }
 

package/theme/GlossaryTerm/index.js

@@ -1,4 +1,5 @@
-import React, { useState } from 'react';
+import React, { useMemo, useState } from 'react';
+import {usePluginData} from '@docusaurus/useGlobalData';
 import styles from './styles.module.css';
 
 /**
@@ -20,13 +21,31 @@ import styles from './styles.module.css';
 export default function GlossaryTerm({ term, definition, routePath = '/glossary', children }) {
   const [showTooltip, setShowTooltip] = useState(false);
 
+  // Pull definition/route from plugin global data if not provided
+  const pluginData = usePluginData('docusaurus-plugin-glossary');
+  const effectiveDefinition = useMemo(() => {
+    if (definition && typeof definition === 'string' && definition.length > 0) {
+      return definition;
+    }
+    const terms = (pluginData && pluginData.terms) || [];
+    const found = terms.find(
+      (t) => typeof t.term === 'string' && t.term.toLowerCase() === String(term).toLowerCase()
+    );
+    return found && found.definition ? found.definition : undefined;
+  }, [definition, pluginData, term]);
+
+  const effectiveRoutePath = useMemo(() => {
+    if (routePath && typeof routePath === 'string' && routePath.length > 0) return routePath;
+    return (pluginData && pluginData.routePath) || '/glossary';
+  }, [pluginData, routePath]);
+
   const displayText = children || term;
   const termId = term.toLowerCase().replace(/\s+/g, '-');
 
   return (
     <span className={styles.glossaryTermWrapper}>
       <a
-        href={`${routePath}#${termId}`}
+        href={`${effectiveRoutePath}#${termId}`}
         className={styles.glossaryTerm}
         onMouseEnter={() => setShowTooltip(true)}
         onMouseLeave={() => setShowTooltip(false)}
@@ -36,13 +55,13 @@ export default function GlossaryTerm({ term, definition, routePath = '/glossary'
       >
         {displayText}
       </a>
-      {definition && (
+      {effectiveDefinition && (
         <span
           id={`tooltip-${termId}`}
           className={`${styles.tooltip} ${showTooltip ? styles.tooltipVisible : ''}`}
           role="tooltip"
         >
-          <strong>{term}:</strong> {definition}
+          <strong>{term}:</strong> {effectiveDefinition}
         </span>
       )}
     </span>