docusaurus-plugin-glossary 1.0.0 → 1.0.2

package/README.md

@@ -7,111 +7,83 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
 - **Auto-generated Glossary Page**: Displays all terms alphabetically with letter navigation
 - **Search Functionality**: Real-time search across terms and definitions
 - **GlossaryTerm Component**: Inline component for linking terms with tooltip previews
+- **Automatic Term Detection**: Automatically detect and link glossary terms in markdown files with tooltips
 - **Responsive Design**: Mobile-friendly UI with dark mode support
 - **Related Terms**: Link between related glossary terms
 - **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
-   plugins: [
-     [
-       require.resolve('./src/plugins/docusaurus-plugin-glossary'),
-       {
-         glossaryPath: 'glossary/glossary.json', // optional, default: 'glossary/glossary.json'
-         routePath: '/glossary', // optional, default: '/glossary'
-       },
+   module.exports = {
+     // ... other config
+     plugins: [
+       [
+         'docusaurus-plugin-glossary',
+         {
+           glossaryPath: 'glossary/glossary.json', // Path to your glossary file
+           routePath: '/glossary', // URL path for glossary page
+           autoLinkTerms: true, // Automatically link terms (default: true)
+         },
+       ],
      ],
-   ];
-   ```
-
-### 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
-   ├── theme/
-   │   └── GlossaryTerm/
-   │       ├── index.js
-   │       └── styles.module.css
-   ├── package.json
-   └── README.md
+     // ... other config
+   };
    ```
+   
+   **That's it!** The remark plugin is automatically configured - no manual `markdown.remarkPlugins` setup needed.
 
-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",
-     "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"
-     }
+     "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
-   plugins: [
-     [
-       'docusaurus-plugin-glossary',
-       {
-         glossaryPath: 'glossary/glossary.json',
-         routePath: '/glossary',
-       },
-     ],
-   ];
-   ```
+### Install from npm (Recommended)
+
+```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
 {
@@ -133,54 +105,148 @@ 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`!
 
-Each term object can include:
+**Advanced: Manual Remark Plugin Configuration**
 
-- `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)
+If you need more control or want to disable automatic detection, you can manually configure the remark plugin:
 
-### 3. Using the GlossaryTerm Component
+```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(),
+        },
+      ],
+    ],
+  },
+};
+```
 
-Import and use the `GlossaryTerm` component in your MDX files:
+### Step 3: Use Glossary Terms in Your Content
+
+#### 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.
+
+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
+- Styled with a dotted underline
+- Display a tooltip with the definition on hover
+- Link to the full glossary page entry
+
+**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
+
+#### Option B: Manual Component Usage
+
+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)
 
-### 4. 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                                           |
-| -------------- | ------ | -------------------------- | ----------------------------------------------------- |
-| `glossaryPath` | string | `'glossary/glossary.json'` | Path to glossary JSON file relative to site directory |
-| `routePath`    | string | `'/glossary'`              | URL path for glossary page                            |
+| Option         | Type    | Default                    | Description                                           |
+| -------------- | ------- | -------------------------- | ----------------------------------------------------- |
+| `glossaryPath` | string  | `'glossary/glossary.json'` | Path to glossary JSON file relative to site directory |
+| `routePath`    | string  | `'/glossary'`              | URL path for glossary page                            |
+| `autoLinkTerms`| boolean | `true`                     | Enable automatic term detection in markdown (requires remark plugin configuration) |
 
 ## Customization
 
@@ -226,12 +292,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.",
@@ -241,7 +321,22 @@ themeConfig: {
 }
 ```
 
-### Example 2: Using in MDX
+### Writing Content with Automatic Detection
+
+```markdown
+---
+title: API Documentation
+---
+
+# Getting Started with Our API
+
+Our API uses RESTful principles to provide a simple and consistent interface.
+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.
+
+### Using the Component in MDX
 
 ```mdx
 ---
@@ -252,8 +347,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.
 ```
 
@@ -267,6 +362,8 @@ docusaurus-plugin-glossary/
 ├── 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
@@ -281,6 +378,15 @@ docusaurus-plugin-glossary/
 3. **getThemePath**: Exposes theme components
 4. **getPathsToWatch**: Watches glossary file for changes
 
+### Remark Plugin
+
+The remark plugin (`remark/glossary-terms.js`) automatically detects glossary terms in markdown files and replaces them with `GlossaryTerm` components. It:
+
+- Scans text nodes for glossary terms (case-insensitive, whole word matching)
+- Replaces matching terms with MDX components that show tooltips
+- Skips terms inside code blocks, links, or existing MDX components
+- Respects word boundaries to avoid partial matches
+
 ## Troubleshooting
 
 ### Glossary page returns 404
@@ -301,6 +407,16 @@ docusaurus-plugin-glossary/
 - Try clearing cache with `npm run clear`
 - Restart dev server
 
+### Automatic term detection not working
+
+- 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
 
 - Check for CSS conflicts in your custom CSS

package/index.js

@@ -9,29 +9,74 @@ const fs = require('fs-extra');
  * - Auto-generated glossary page
  * - GlossaryTerm component for inline definitions
  * - Tooltips on hover
+ * - Automatic glossary term detection in markdown files
  *
  * @param {object} context - Docusaurus context
  * @param {object} options - Plugin options
  * @param {string} options.glossaryPath - Path to glossary JSON file (default: 'glossary/glossary.json')
  * @param {string} options.routePath - Route path for glossary page (default: '/glossary')
+ * @param {boolean} options.autoLinkTerms - Automatically link glossary terms in markdown (default: true)
  * @returns {object} Plugin object
  */
 function glossaryPlugin(context, options = {}) {
-  const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary' } = options;
+  const { 
+    glossaryPath = 'glossary/glossary.json', 
+    routePath = '/glossary',
+    autoLinkTerms = true
+  } = options;
+
+  let glossaryDataCache = { terms: [] };
 
   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);
 
       if (await fs.pathExists(glossaryFilePath)) {
         const glossaryData = await fs.readJson(glossaryFilePath);
+        glossaryDataCache = glossaryData;
         return glossaryData;
       }
 
       console.warn(`Glossary file not found at ${glossaryFilePath}. Using empty glossary.`);
+      glossaryDataCache = { terms: [] };
       return { terms: [] };
     },
 
@@ -40,11 +85,20 @@ function glossaryPlugin(context, options = {}) {
 
       // Create data file that can be imported by components
       const glossaryDataPath = await createData('glossary-data.json', JSON.stringify(content));
+      
+      // Create a data file for the remark plugin to access glossary terms
+      const remarkGlossaryDataPath = await createData(
+        'remark-glossary-data.json',
+        JSON.stringify({
+          terms: content.terms || [],
+          routePath: routePath,
+        })
+      );
 
       // Add glossary page route
       addRoute({
         path: routePath,
-        component: '@site/src/plugins/docusaurus-plugin-glossary/components/GlossaryPage.js',
+        component: path.join(__dirname, 'components/GlossaryPage.js'),
         exact: true,
         modules: {
           glossaryData: glossaryDataPath,
@@ -67,4 +121,32 @@ function glossaryPlugin(context, options = {}) {
   };
 }
 
+// Export remark plugin factory for use in markdown configuration
+glossaryPlugin.remarkPlugin = require('./remark/glossary-terms');
+
+/**
+ * Helper function to get the configured remark plugin
+ * This can be used in docusaurus.config.js markdown configuration
+ * 
+ * @param {object} pluginOptions - Plugin options from docusaurus.config.js
+ * @param {object} context - Docusaurus context
+ * @returns {function} Configured remark plugin
+ */
+glossaryPlugin.getRemarkPlugin = function(pluginOptions, context) {
+  const { 
+    glossaryPath = 'glossary/glossary.json', 
+    routePath = '/glossary',
+    siteDir = context.siteDir
+  } = pluginOptions;
+
+  return [
+    require('./remark/glossary-terms'),
+    {
+      glossaryPath,
+      routePath,
+      siteDir,
+    }
+  ];
+};
+
 module.exports = glossaryPlugin;

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "docusaurus-plugin-glossary",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
   "main": "index.js",
   "files": [
     "index.js",
     "components/",
     "theme/",
+    "remark/",
     "README.md",
     "LICENSE"
   ],
@@ -44,7 +45,8 @@
     "react-dom": "^18.0.0"
   },
   "dependencies": {
-    "fs-extra": "^11.0.0"
+    "fs-extra": "^11.0.0",
+    "unist-util-visit": "^5.0.0"
   },
   "engines": {
     "node": ">=16.14"

package/remark/glossary-terms.js

@@ -0,0 +1,214 @@
+const visit = require('unist-util-visit');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Creates a remark plugin that automatically detects and replaces glossary terms in markdown
+ * 
+ * @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)
+ * @param {string} options.routePath - Route path to glossary page (default: '/glossary')
+ * @param {string} options.siteDir - Docusaurus site directory (required if using glossaryPath)
+ * @returns {function} Remark plugin function
+ */
+function remarkGlossaryTerms({ 
+  terms = [], 
+  glossaryPath = null,
+  routePath = '/glossary',
+  siteDir = null
+} = {}) {
+  let glossaryTerms = terms;
+
+  // If terms not provided, try to load from glossaryPath (synchronously)
+  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 || [];
+      }
+    } catch (error) {
+      console.warn(`Failed to load glossary from ${glossaryPath}:`, error.message);
+    }
+  }
+
+  // Build a map of terms for efficient lookup
+  // Key: lowercase term, Value: term object with original case
+  const termMap = new Map();
+  glossaryTerms.forEach(termObj => {
+    if (termObj.term) {
+      termMap.set(termObj.term.toLowerCase(), termObj);
+    }
+  });
+
+  // Sort terms by length (longest first) to avoid partial matches
+  // e.g., "Application Programming Interface" should match before "API"
+  const sortedTerms = Array.from(termMap.entries()).sort(
+    (a, b) => b[0].length - a[0].length
+  );
+
+  // If no terms, return a no-op transformer
+  if (sortedTerms.length === 0) {
+    return (tree) => tree;
+  }
+
+  /**
+   * Recursively replace glossary terms in text
+   * Returns an array of text nodes and MDX components
+   */
+  function replaceTermsInText(text, position) {
+    if (!text || !sortedTerms.length) {
+      return [{ type: 'text', value: text }];
+    }
+
+    const result = [];
+    let lastIndex = 0;
+    let textLower = text.toLowerCase();
+
+    // Find all matches
+    const matches = [];
+    for (const [lowerTerm, termObj] of sortedTerms) {
+      const term = termObj.term;
+      let searchIndex = 0;
+      
+      while (searchIndex < textLower.length) {
+        const index = textLower.indexOf(lowerTerm, searchIndex);
+        if (index === -1) break;
+
+        // Check if it's a whole word match
+        const beforeChar = index > 0 ? textLower[index - 1] : ' ';
+        const afterChar = index + lowerTerm.length < textLower.length 
+          ? textLower[index + lowerTerm.length] 
+          : ' ';
+        
+        // Word boundary check (alphanumeric characters)
+        const isWordBoundary = 
+          !/\w/.test(beforeChar) && !/\w/.test(afterChar);
+
+        if (isWordBoundary) {
+          matches.push({
+            index,
+            length: term.length,
+            term: term,
+            termObj: termObj,
+            // Store original case from the text
+            originalText: text.substring(index, index + term.length)
+          });
+        }
+
+        searchIndex = index + 1;
+      }
+    }
+
+    // Sort matches by index
+    matches.sort((a, b) => a.index - b.index);
+
+    // Remove overlapping matches (keep the first one)
+    const nonOverlappingMatches = [];
+    let lastMatchEnd = 0;
+    for (const match of matches) {
+      if (match.index >= lastMatchEnd) {
+        nonOverlappingMatches.push(match);
+        lastMatchEnd = match.index + match.length;
+      }
+    }
+
+    // Build result array
+    for (const match of nonOverlappingMatches) {
+      // Add text before match
+      if (match.index > lastIndex) {
+        result.push({
+          type: 'text',
+          value: text.substring(lastIndex, match.index)
+        });
+      }
+
+      // Add MDX component for glossary term
+      result.push({
+        type: 'mdxJsxFlowElement',
+        name: 'GlossaryTerm',
+        attributes: [
+          {
+            type: 'mdxJsxAttribute',
+            name: 'term',
+            value: match.termObj.term
+          },
+          {
+            type: 'mdxJsxAttribute',
+            name: 'definition',
+            value: match.termObj.definition || ''
+          },
+          {
+            type: 'mdxJsxAttribute',
+            name: 'routePath',
+            value: routePath
+          }
+        ],
+        children: [
+          {
+            type: 'text',
+            value: match.originalText
+          }
+        ]
+      });
+
+      lastIndex = match.index + match.length;
+    }
+
+    // Add remaining text
+    if (lastIndex < text.length) {
+      result.push({
+        type: 'text',
+        value: text.substring(lastIndex)
+      });
+    }
+
+    return result.length > 0 ? result : [{ type: 'text', value: text }];
+  }
+
+  return (tree) => {
+    visit(tree, 'text', (node, index, parent) => {
+      // Skip text nodes inside code blocks, links, or existing MDX components
+      if (
+        parent.type === 'code' ||
+        parent.type === 'inlineCode' ||
+        parent.type === 'link' ||
+        parent.type === 'mdxJsxFlowElement' ||
+        parent.type === 'mdxJsxTextElement'
+      ) {
+        return;
+      }
+
+      // Replace terms in text node
+      const replacements = replaceTermsInText(node.value);
+
+      // If we have replacements, replace the single text node with multiple nodes
+      if (replacements.length > 1 || 
+          (replacements.length === 1 && replacements[0].type !== 'text')) {
+        // Convert to text elements for paragraph context if needed
+        const newNodes = replacements.map(replacement => {
+          if (replacement.type === 'mdxJsxFlowElement') {
+            // In paragraph context, we need mdxJsxTextElement instead
+            if (parent.type === 'paragraph') {
+              return {
+                type: 'mdxJsxTextElement',
+                name: replacement.name,
+                attributes: replacement.attributes,
+                children: replacement.children
+              };
+            }
+          }
+          return replacement;
+        });
+
+        // Replace the single node with multiple nodes
+        parent.children.splice(index, 1, ...newNodes);
+        return index + newNodes.length - 1; // Return new index to continue
+      }
+    });
+  };
+}
+
+module.exports = remarkGlossaryTerms;
+

package/theme/GlossaryTerm/index.js

@@ -14,9 +14,10 @@ import styles from './styles.module.css';
  * @param {object} props
  * @param {string} props.term - The glossary term
  * @param {string} props.definition - The definition to show in tooltip
+ * @param {string} props.routePath - Route path to glossary page (default: '/glossary')
  * @param {React.ReactNode} props.children - Optional custom display text
  */
-export default function GlossaryTerm({ term, definition, children }) {
+export default function GlossaryTerm({ term, definition, routePath = '/glossary', children }) {
   const [showTooltip, setShowTooltip] = useState(false);
 
   const displayText = children || term;
@@ -25,7 +26,7 @@ export default function GlossaryTerm({ term, definition, children }) {
   return (
     <span className={styles.glossaryTermWrapper}>
       <a
-        href={`/glossary#${termId}`}
+        href={`${routePath}#${termId}`}
         className={styles.glossaryTerm}
         onMouseEnter={() => setShowTooltip(true)}
         onMouseLeave={() => setShowTooltip(false)}

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 {