docusaurus-plugin-glossary 1.0.0 → 1.0.1

package/README.md

@@ -7,6 +7,7 @@ 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
@@ -24,15 +25,44 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
 
 2. Add the plugin 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'
-       },
+   const glossaryPlugin = require.resolve('./src/plugins/docusaurus-plugin-glossary');
+
+   module.exports = {
+     // ... other config
+     plugins: [
+       [
+         glossaryPlugin,
+         {
+           glossaryPath: 'glossary/glossary.json', // optional, default: 'glossary/glossary.json'
+           routePath: '/glossary', // optional, default: '/glossary'
+           autoLinkTerms: true, // optional, default: true - automatically link terms in markdown
+         },
+       ],
      ],
-   ];
+     // ... other config
+   };
+   ```
+
+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)
@@ -54,6 +84,8 @@ To publish this as a separate npm package:
    ├── components/
    │   ├── GlossaryPage.js
    │   └── GlossaryPage.module.css
+   ├── remark/
+   │   └── glossary-terms.js
    ├── theme/
    │   └── GlossaryTerm/
    │       ├── index.js
@@ -70,6 +102,14 @@ To publish this as a separate npm package:
      "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",
@@ -77,7 +117,11 @@ To publish this as a separate npm package:
        "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"
      }
    }
    ```
@@ -96,15 +140,43 @@ To publish this as a separate npm package:
 
 6. Add to your `docusaurus.config.js`:
    ```javascript
-   plugins: [
-     [
-       'docusaurus-plugin-glossary',
-       {
-         glossaryPath: 'glossary/glossary.json',
-         routePath: '/glossary',
-       },
+   const glossaryPlugin = require('docusaurus-plugin-glossary');
+   
+   module.exports = {
+     // ... other config
+     plugins: [
+       [
+         'docusaurus-plugin-glossary',
+         {
+           glossaryPath: 'glossary/glossary.json',
+           routePath: '/glossary',
+         },
+       ],
      ],
-   ];
+     // ... other config
+   };
+   ```
+
+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
+   };
    ```
 
 ## Usage
@@ -143,9 +215,26 @@ Each term object can include:
 - `relatedTerms` (optional): Array of related term names
 - `id` (optional): Custom ID for linking (auto-generated from term if not provided)
 
-### 3. Using the GlossaryTerm Component
+### 3. Automatic Term Detection
+
+When the remark plugin is configured (see Installation), glossary terms are automatically detected and linked in all 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 and will appear with:
+- Dotted underline styling
+- Tooltip showing definition on hover
+- Link to 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.
+
+### 4. Using the GlossaryTerm Component Manually
 
-Import and use the `GlossaryTerm` component in your MDX files:
+For more control or when automatic detection isn't sufficient, you can manually import and use the `GlossaryTerm` component in your MDX files:
 
 ```jsx
 import GlossaryTerm from '@theme/GlossaryTerm';
@@ -163,7 +252,7 @@ The component features:
 - Link to full glossary page entry
 - Accessible with keyboard navigation
 
-### 4. Accessing the Glossary Page
+### 5. Accessing the Glossary Page
 
 The glossary page is automatically available at `/glossary` (or your configured `routePath`).
 
@@ -177,10 +266,11 @@ Features:
 
 ## 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
 
@@ -241,7 +331,24 @@ themeConfig: {
 }
 ```
 
-### Example 2: Using in MDX
+### Example 2: Automatic Term Detection
+
+With the remark plugin configured, you can simply write markdown normally:
+
+```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.
+
+### Example 3: Using in MDX Manually
 
 ```mdx
 ---
@@ -267,6 +374,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 +390,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 +419,14 @@ docusaurus-plugin-glossary/
 - Try clearing cache with `npm run clear`
 - Restart dev server
 
+### 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
+- 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
+
 ### Styles not applying
 
 - Check for CSS conflicts in your custom CSS

package/index.js

@@ -9,15 +9,23 @@ 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',
@@ -28,10 +36,12 @@ function glossaryPlugin(context, options = {}) {
 
       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 +50,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 +86,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.1",
   "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)}