docusaurus-plugin-glossary 1.0.1 → 1.1.0

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
@@ -13,177 +15,77 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
 - **Abbreviation Support**: Display full form of abbreviated terms
 - **Customizable**: Configure glossary path and route
 
-## Installation
-
-### For Local Use (Same Repository)
-
-1. Copy the plugin directory to your Docusaurus site:
+## Quick Start
 
-   ```
-   src/plugins/docusaurus-plugin-glossary/
+1. **Install the plugin:**
+   ```bash
+   npm install docusaurus-plugin-glossary
    ```
 
-2. Add the plugin to your `docusaurus.config.js`:
+2. **Add to your `docusaurus.config.js`:**
    ```javascript
-   const glossaryPlugin = require.resolve('./src/plugins/docusaurus-plugin-glossary');
-
    module.exports = {
      // ... other config
      plugins: [
        [
-         glossaryPlugin,
+         'docusaurus-plugin-glossary',
          {
-           glossaryPath: 'glossary/glossary.json', // optional, default: 'glossary/glossary.json'
-           routePath: '/glossary', // optional, default: '/glossary'
-           autoLinkTerms: true, // optional, default: true - automatically link terms in markdown
+           glossaryPath: 'glossary/glossary.json', // Path to your glossary file
+           routePath: '/glossary', // URL path for glossary page
+           autoLinkTerms: true, // Automatically link terms (default: true)
          },
        ],
      ],
      // ... other config
    };
    ```
+   
+   **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. **Enable automatic term detection** by adding the remark plugin to your markdown configuration:
-   ```javascript
-   const glossaryPlugin = require('./src/plugins/docusaurus-plugin-glossary');
-
-   module.exports = {
-     // ... other config
-     markdown: {
-       remarkPlugins: [
-         [
-           glossaryPlugin.remarkPlugin,
-           {
-             glossaryPath: 'glossary/glossary.json',
-             routePath: '/glossary',
-             siteDir: process.cwd(), // or your site directory
-           },
-         ],
-       ],
-     },
-     // ... other config
-   };
-   ```
-
-### For Separate Package (To Publish)
-
-To publish this as a separate npm package:
-
-1. Create a new directory for the package:
-
-   ```bash
-   mkdir docusaurus-plugin-glossary
-   cd docusaurus-plugin-glossary
-   ```
-
-2. Copy the plugin files:
-
-   ```
-   docusaurus-plugin-glossary/
-   ├── index.js
-   ├── components/
-   │   ├── GlossaryPage.js
-   │   └── GlossaryPage.module.css
-   ├── remark/
-   │   └── glossary-terms.js
-   ├── theme/
-   │   └── GlossaryTerm/
-   │       ├── index.js
-   │       └── styles.module.css
-   ├── package.json
-   └── README.md
-   ```
-
-3. Create a `package.json`:
-
+3. **Create your glossary file at `glossary/glossary.json`:**
    ```json
    {
-     "name": "docusaurus-plugin-glossary",
-     "version": "1.0.0",
-     "description": "A Docusaurus plugin for creating and managing glossary terms",
-     "main": "index.js",
-     "files": [
-       "index.js",
-       "components/",
-       "theme/",
-       "remark/",
-       "README.md",
-       "LICENSE"
-     ],
-     "keywords": ["docusaurus", "glossary", "plugin", "documentation"],
-     "peerDependencies": {
-       "@docusaurus/core": "^3.0.0",
-       "react": "^18.0.0",
-       "react-dom": "^18.0.0"
-     },
-     "dependencies": {
-       "fs-extra": "^11.0.0",
-       "unist-util-visit": "^5.0.0"
-     },
-     "engines": {
-       "node": ">=16.14"
-     }
+     "description": "A collection of technical terms and their definitions",
+     "terms": [
+       {
+         "term": "API",
+         "abbreviation": "Application Programming Interface",
+         "definition": "A set of rules and protocols that allows different software applications to communicate with each other.",
+         "relatedTerms": ["REST", "GraphQL"]
+       },
+       {
+         "term": "REST",
+         "abbreviation": "Representational State Transfer",
+         "definition": "An architectural style for designing networked applications.",
+         "relatedTerms": ["API", "HTTP"]
+       }
+     ]
    }
    ```
 
-4. Publish to npm:
-
+4. **Start your dev server:**
    ```bash
-   npm publish
+   npm run start
    ```
 
-5. Install in your Docusaurus site:
+5. **That's it!** 
+   - Visit `/glossary` to see your glossary page
+   - Write markdown normally - terms will automatically be linked with tooltips
+   - Use `<GlossaryTerm>` component in MDX for manual control
 
-   ```bash
-   npm install docusaurus-plugin-glossary
-   ```
+## Installation
 
-6. Add to your `docusaurus.config.js`:
-   ```javascript
-   const glossaryPlugin = require('docusaurus-plugin-glossary');
-   
-   module.exports = {
-     // ... other config
-     plugins: [
-       [
-         'docusaurus-plugin-glossary',
-         {
-           glossaryPath: 'glossary/glossary.json',
-           routePath: '/glossary',
-         },
-       ],
-     ],
-     // ... other config
-   };
-   ```
+### Install from npm (Recommended)
 
-7. **Enable automatic term detection** by adding the remark plugin to your markdown configuration:
-   ```javascript
-   const glossaryPlugin = require('docusaurus-plugin-glossary');
-   
-   module.exports = {
-     // ... other config
-     markdown: {
-       remarkPlugins: [
-         [
-           glossaryPlugin.remarkPlugin,
-           {
-             glossaryPath: 'glossary/glossary.json',
-             routePath: '/glossary',
-             siteDir: process.cwd(), // or your site directory
-           },
-         ],
-       ],
-     },
-     // ... other config
-   };
-   ```
+```bash
+npm install docusaurus-plugin-glossary
+```
 
-## Usage
+## Usage Guide
 
-### 1. Create a Glossary Data File
+### Step 1: Create Your Glossary File
 
-Create a JSON file at `glossary/glossary.json` (or your configured path):
+Create a JSON file at `glossary/glossary.json` (or your configured path) in your Docusaurus site root:
 
 ```json
 {
@@ -205,19 +107,92 @@ Create a JSON file at `glossary/glossary.json` (or your configured path):
 }
 ```
 
-### 2. Glossary Data Structure
+**Required fields:**
+- `term` (string): The glossary term name
+- `definition` (string): The term's definition
+
+**Optional fields:**
+- `abbreviation` (string): The full form if the term is an abbreviation
+- `relatedTerms` (string[]): Array of related term names that link to other glossary entries
+- `id` (string): Custom ID for linking (auto-generated from term name if not provided)
+
+### Step 2: Configure the Plugin
+
+Add the plugin to your `docusaurus.config.js`:
+
+```javascript
+module.exports = {
+  plugins: [
+    [
+      'docusaurus-plugin-glossary',
+      {
+        glossaryPath: 'glossary/glossary.json', // Path to your glossary file
+        routePath: '/glossary', // URL path for the glossary page
+        autoLinkTerms: true, // Automatically detect and link terms (default: true)
+      },
+    ],
+  ],
+};
+```
+
+**Automatic Configuration:** The remark plugin is automatically configured when `autoLinkTerms` is `true` (the default). You don't need to manually configure `markdown.remarkPlugins`!
+
+**Advanced: Manual Remark Plugin Configuration**
+
+If you need more control or want to disable automatic detection, you can manually configure the remark plugin:
+
+```javascript
+const glossaryPlugin = require('docusaurus-plugin-glossary');
+
+module.exports = {
+  plugins: [
+    [
+      'docusaurus-plugin-glossary',
+      {
+        glossaryPath: 'glossary/glossary.json',
+        routePath: '/glossary',
+        autoLinkTerms: false, // Disable automatic configuration
+      },
+    ],
+  ],
+  markdown: {
+    remarkPlugins: [
+      [
+        glossaryPlugin.remarkPlugin,
+        {
+          glossaryPath: 'glossary/glossary.json',
+          routePath: '/glossary',
+          siteDir: process.cwd(),
+        },
+      ],
+    ],
+  },
+};
+```
+
+## 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.
+  ```
 
-Each term object can include:
+- **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.
 
-- `term` (required): The glossary term
-- `definition` (required): The term's definition
-- `abbreviation` (optional): The full form if the term is an abbreviation
-- `relatedTerms` (optional): Array of related term names
-- `id` (optional): Custom ID for linking (auto-generated from term if not provided)
+- **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.
 
-### 3. Automatic Term Detection
+### Step 3: Use Glossary Terms in Your Content
 
-When the remark plugin is configured (see Installation), glossary terms are automatically detected and linked in all markdown files. Simply write your content normally:
+#### Option A: Automatic Detection (Recommended)
+
+With the remark plugin configured, glossary terms are **automatically detected and linked** in all your markdown files. Simply write your content normally:
 
 ```markdown
 Our API uses REST principles to provide a simple interface.
@@ -225,45 +200,66 @@ Our API uses REST principles to provide a simple interface.
 This project supports webhooks for real-time notifications.
 ```
 
-Terms like "API", "REST", and "webhooks" will automatically be detected if they're defined in your glossary and will appear with:
-- Dotted underline styling
-- Tooltip showing definition on hover
-- Link to full glossary page entry
+Terms like "API", "REST", and "webhooks" will automatically be:
+- Detected if they're defined in your glossary
+- Styled with a dotted underline
+- Display a tooltip with the definition on hover
+- Link to the full glossary page entry
 
-**Note**: Automatic detection works for whole words only and respects word boundaries. Terms inside code blocks, links, or existing MDX components are not processed.
+**Limitations:**
+- Only whole words are matched (respects word boundaries)
+- Terms inside code blocks, links, or existing MDX components are **not** processed
+- Matching is case-insensitive
 
-### 4. Using the GlossaryTerm Component Manually
+#### Option B: Manual Component Usage
 
-For more control or when automatic detection isn't sufficient, you can manually import and use the `GlossaryTerm` component in your MDX files:
+For more control or when automatic detection isn't sufficient, use the `GlossaryTerm` component in MDX files:
 
 ```jsx
 import GlossaryTerm from '@theme/GlossaryTerm';
 
-This website uses an <GlossaryTerm term="API" definition="Application Programming Interface">API</GlossaryTerm> to fetch data.
+This website uses an <GlossaryTerm term="API">API</GlossaryTerm> to fetch data.
 
-// Or with default display (term name):
-We use <GlossaryTerm term="REST" definition="Representational State Transfer" /> for our web services.
-```
+// Or with explicit definition (overrides glossary entry):
+We use <GlossaryTerm term="REST" definition="Representational State Transfer" /> for our services.
 
-The component features:
+// Or with children content:
+Our <GlossaryTerm term="API" definition="Application Programming Interface">RESTful API</GlossaryTerm> is available.
+```
 
-- Dotted underline styling
-- Tooltip showing definition on hover
-- Link to full glossary page entry
-- Accessible with keyboard navigation
+**Component props:**
+- `term` (required): The term name (used to look up definition from glossary)
+- `definition` (optional): Override the definition from the glossary file
+- `children` (optional): Custom text to display (defaults to term name)
 
-### 5. Accessing the Glossary Page
+### Step 4: Access the Glossary Page
 
 The glossary page is automatically available at `/glossary` (or your configured `routePath`).
 
-Features:
-
+**Features:**
 - Alphabetical grouping with letter navigation
-- Real-time search
-- Related terms linking
+- Real-time search across terms and definitions
+- Clickable related terms
 - Responsive design
 - Dark mode support
 
+**Add to navigation:**
+
+To add the glossary to your navbar, update your `docusaurus.config.js`:
+
+```javascript
+module.exports = {
+  themeConfig: {
+    navbar: {
+      items: [
+        {to: '/glossary', label: 'Glossary', position: 'left'},
+        // ... other items
+      ],
+    },
+  },
+};
+```
+
 ## Configuration Options
 
 | Option         | Type    | Default                    | Description                                           |
@@ -316,12 +312,26 @@ themeConfig: {
 
 ## Examples
 
-### Example 1: Technical Documentation
+See the [Usage Guide](#usage-guide) section above for complete examples. Here are additional examples:
+
+### Complete Glossary Example
 
 ```json
 {
   "description": "Technical terms used in our documentation",
   "terms": [
+    {
+      "term": "API",
+      "abbreviation": "Application Programming Interface",
+      "definition": "A set of rules and protocols that allows different software applications to communicate with each other.",
+      "relatedTerms": ["REST", "GraphQL", "Webhook"]
+    },
+    {
+      "term": "REST",
+      "abbreviation": "Representational State Transfer",
+      "definition": "An architectural style for designing networked applications.",
+      "relatedTerms": ["API", "HTTP"]
+    },
     {
       "term": "Webhook",
       "definition": "An HTTP callback that occurs when something happens; a simple event-notification via HTTP POST.",
@@ -331,9 +341,7 @@ themeConfig: {
 }
 ```
 
-### Example 2: Automatic Term Detection
-
-With the remark plugin configured, you can simply write markdown normally:
+### Writing Content with Automatic Detection
 
 ```markdown
 ---
@@ -348,7 +356,7 @@ Webhooks are supported for real-time event notifications.
 
 The terms "API", "RESTful", and "Webhooks" will automatically be detected and linked if they're defined in your glossary.
 
-### Example 3: Using in MDX Manually
+### Using the Component in MDX
 
 ```mdx
 ---
@@ -359,8 +367,8 @@ import GlossaryTerm from '@theme/GlossaryTerm';
 
 # Getting Started with Our API
 
-Our <GlossaryTerm term="API" definition="Application Programming Interface" />
-uses <GlossaryTerm term="REST" definition="Representational State Transfer">RESTful</GlossaryTerm>
+Our <GlossaryTerm term="API" />
+uses <GlossaryTerm term="REST">RESTful</GlossaryTerm>
 principles to provide a simple and consistent interface.
 ```
 
@@ -421,11 +429,13 @@ The remark plugin (`remark/glossary-terms.js`) automatically detects glossary te
 
 ### Automatic term detection not working
 
-- Ensure the remark plugin is configured in `markdown.remarkPlugins` in `docusaurus.config.js`
-- Check that `glossaryPath` and `siteDir` are correctly configured in the remark plugin options
-- Verify your glossary file exists and contains terms
+- Ensure `autoLinkTerms` is `true` (the default) in your plugin configuration
+- The remark plugin is automatically configured, so you don't need to manually add it to `markdown.remarkPlugins`
+- Verify your glossary file exists at the configured `glossaryPath` and contains terms
+- Check that terms in your content match the terms in your glossary (matching is case-insensitive but respects word boundaries)
 - Try clearing cache with `npm run clear` and restarting the dev server
 - Note that terms inside code blocks, links, or MDX components are not processed
+- If you've manually configured the remark plugin, ensure `siteDir` points to the correct Docusaurus site directory
 
 ### Styles not applying
 

package/index.js

@@ -30,6 +30,41 @@ function glossaryPlugin(context, options = {}) {
   return {
     name: 'docusaurus-plugin-glossary',
 
+    configureMarkdown(markdownConfig) {
+      // Automatically configure the remark plugin if autoLinkTerms is enabled
+      if (autoLinkTerms) {
+        if (!markdownConfig.remarkPlugins) {
+          markdownConfig.remarkPlugins = [];
+        }
+
+        const remarkPlugin = require('./remark/glossary-terms');
+
+        // Check if the remark plugin is already configured
+        const isAlreadyConfigured = markdownConfig.remarkPlugins.some(
+          (plugin) => {
+            if (Array.isArray(plugin) && plugin[0]) {
+              // Check if it's our remark plugin by comparing the function reference
+              return plugin[0] === remarkPlugin;
+            }
+            // Also check if it's directly the remark plugin function
+            return plugin === remarkPlugin;
+          }
+        );
+
+        // Only add if not already configured
+        if (!isAlreadyConfigured) {
+          markdownConfig.remarkPlugins.push([
+            remarkPlugin,
+            {
+              glossaryPath,
+              routePath,
+              siteDir: context.siteDir,
+            }
+          ]);
+        }
+      }
+    },
+
     async loadContent() {
       // Load glossary terms from JSON file
       const glossaryFilePath = path.resolve(context.siteDir, glossaryPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-glossary",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
   "main": "index.js",
   "files": [

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/styles.module.css

@@ -33,10 +33,11 @@
   white-space: normal;
   max-width: 300px;
   min-width: 200px;
-  z-index: 1000;
+  z-index: 9999;
   opacity: 0;
   pointer-events: none;
   transition: opacity 0.2s;
+  visibility: hidden;
 }
 
 .tooltip::after {
@@ -63,6 +64,7 @@
 .tooltipVisible {
   opacity: 1;
   pointer-events: auto;
+  visibility: visible;
 }
 
 .tooltip strong {