docusaurus-plugin-glossary 1.1.2 → 1.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 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).
+> 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.
 
 ## Features
 
@@ -18,31 +18,66 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
 ## Quick Start
 
 1. **Install the plugin:**
+
    ```bash
    npm install docusaurus-plugin-glossary
    ```
 
 2. **Add to your `docusaurus.config.js`:**
+
    ```javascript
+   const glossaryPlugin = require('docusaurus-plugin-glossary');
+
    module.exports = {
      // ... other config
+     presets: [
+       [
+         '@docusaurus/preset-classic',
+         {
+           docs: {
+             // Add the remark plugin to enable auto-linking in docs
+             remarkPlugins: [
+               glossaryPlugin.getRemarkPlugin(
+                 {
+                   glossaryPath: 'glossary/glossary.json',
+                   routePath: '/glossary',
+                 },
+                 { siteDir: __dirname }
+               ),
+             ],
+           },
+           pages: {
+             // Add the remark plugin to enable auto-linking in pages
+             remarkPlugins: [
+               glossaryPlugin.getRemarkPlugin(
+                 {
+                   glossaryPath: 'glossary/glossary.json',
+                   routePath: '/glossary',
+                 },
+                 { siteDir: __dirname }
+               ),
+             ],
+           },
+         },
+       ],
+     ],
      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)
          },
        ],
      ],
      // ... 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.
+
+   **Note:** You need to configure the remark plugin in both the plugin AND the preset (for docs/pages) to enable auto-linking of terms.
 
 3. **Create your glossary file at `glossary/glossary.json`:**
+
    ```json
    {
      "description": "A collection of technical terms and their definitions",
@@ -64,11 +99,12 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
    ```
 
 4. **Start your dev server:**
+
    ```bash
    npm run start
    ```
 
-5. **That's it!** 
+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
@@ -108,10 +144,12 @@ Create a JSON file at `glossary/glossary.json` (or your configured path) in your
 ```
 
 **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)
@@ -121,72 +159,111 @@ Create a JSON file at `glossary/glossary.json` (or your configured path) in your
 Add the plugin to your `docusaurus.config.js`:
 
 ```javascript
+const glossaryPlugin = require('docusaurus-plugin-glossary');
+
 module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          // Add the remark plugin to enable auto-linking in docs
+          remarkPlugins: [
+            glossaryPlugin.getRemarkPlugin(
+              {
+                glossaryPath: 'glossary/glossary.json',
+                routePath: '/glossary',
+              },
+              { siteDir: __dirname }
+            ),
+          ],
+        },
+        pages: {
+          // Add the remark plugin to enable auto-linking in pages
+          remarkPlugins: [
+            glossaryPlugin.getRemarkPlugin(
+              {
+                glossaryPath: 'glossary/glossary.json',
+                routePath: '/glossary',
+              },
+              { siteDir: __dirname }
+            ),
+          ],
+        },
+      },
+    ],
+  ],
   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`!
+**Required Configuration:** To enable automatic term detection and linking, you must configure the remark plugin in your preset (as shown above). The plugin provides a `getRemarkPlugin` helper to make this easier.
 
-**Advanced: Manual Remark Plugin Configuration**
+**Alternative: Using remarkPlugin directly**
 
-If you need more control or want to disable automatic detection, you can manually configure the remark plugin:
+You can also use the `remarkPlugin` export directly if you prefer:
 
 ```javascript
 const glossaryPlugin = require('docusaurus-plugin-glossary');
 
 module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          remarkPlugins: [
+            [
+              glossaryPlugin.remarkPlugin,
+              {
+                glossaryPath: 'glossary/glossary.json',
+                routePath: '/glossary',
+                siteDir: __dirname,
+              },
+            ],
+          ],
+        },
+      },
+    ],
+  ],
   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.
   ```
 
 - **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.
+  - Confirm you're on `@docusaurus/core@^3` and `react@^18`.
+  - 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.
 
-- **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.
+- **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.
 
 ### Step 3: Use Glossary Terms in Your Content
 
@@ -201,12 +278,14 @@ 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
@@ -228,6 +307,7 @@ Our <GlossaryTerm term="API" definition="Application Programming Interface">REST
 ```
 
 **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)
@@ -237,6 +317,7 @@ Our <GlossaryTerm term="API" definition="Application Programming Interface">REST
 The glossary page is automatically available at `/glossary` (or your configured `routePath`).
 
 **Features:**
+
 - Alphabetical grouping with letter navigation
 - Real-time search across terms and definitions
 - Clickable related terms
@@ -252,7 +333,7 @@ module.exports = {
   themeConfig: {
     navbar: {
       items: [
-        {to: '/glossary', label: 'Glossary', position: 'left'},
+        { to: '/glossary', label: 'Glossary', position: 'left' },
         // ... other items
       ],
     },
@@ -262,11 +343,10 @@ module.exports = {
 
 ## 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                            |
-| `autoLinkTerms`| boolean | `true`                     | Enable automatic term detection in markdown (requires remark plugin configuration) |
+| 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                            |
 
 ## Customization
 
@@ -429,12 +509,12 @@ The remark plugin (`remark/glossary-terms.js`) automatically detects glossary te
 
 ### 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`
+- **IMPORTANT**: Ensure you have configured the remark plugin in your preset (see Configuration section above)
 - 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
+- Make sure you've added the remark plugin to both `docs` and `pages` sections if you want auto-linking in both
 - If you've manually configured the remark plugin, ensure `siteDir` points to the correct Docusaurus site directory
 
 ### Styles not applying
@@ -449,7 +529,7 @@ MIT
 
 ## Contributing
 
-Contributions are welcome! Please open an issue or submit a pull request.
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started.
 
 ## Credits
 

package/lib/index.js

@@ -0,0 +1,246 @@
+var _a, _b;
+import path from 'path';
+import fs from 'fs-extra';
+import { createRequire } from 'module';
+import validatePeerDependencies from 'validate-peer-dependencies';
+import remarkGlossaryTerms from './remark/glossary-terms.js';
+// Helper function to compute __dirname lazily when needed
+// This avoids webpack bundling issues by not using fileURLToPath at module load time
+function getDirname() {
+    var _a;
+    // Check if we're in a Node.js environment
+    if (typeof process === 'undefined' || !((_a = process.versions) === null || _a === void 0 ? void 0 : _a.node)) {
+        return '';
+    }
+    // Use cached value if available
+    if (globalThis.__dirnameCache) {
+        return globalThis.__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) {
+        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);
+            globalThis.__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 '';
+}
+// Initialize __dirname at module load time, but handle webpack bundling gracefully
+let __dirname = '';
+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;
+            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);
+                    validatePeerDependencies(__dirname);
+                    peerDepsValidated = true;
+                }
+            }
+        }
+    }
+}
+catch {
+    // If initialization fails (e.g., during webpack bundling), __dirname will be empty
+    // and will be computed lazily via getDirname() when needed
+}
+// Validate peer dependencies lazily if not already validated
+if (!peerDepsValidated && typeof process !== 'undefined' && ((_b = process.versions) === null || _b === void 0 ? void 0 : _b.node)) {
+    try {
+        const dirname = getDirname();
+        if (dirname) {
+            validatePeerDependencies(dirname);
+            peerDepsValidated = true;
+        }
+    }
+    catch {
+        // Ignore validation errors during webpack bundling
+    }
+}
+/**
+ * Docusaurus Glossary Plugin
+ *
+ * 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)
+ *
+ * IMPORTANT: To enable auto-linking of glossary terms, you must manually add the remark plugin
+ * to your docusaurus.config.js using the getRemarkPlugin helper:
+ *
+ * Example:
+ * ```javascript
+ * const glossaryPlugin = require('docusaurus-plugin-glossary');
+ *
+ * module.exports = {
+ *   presets: [
+ *     ['@docusaurus/preset-classic', {
+ *       docs: {
+ *         remarkPlugins: [
+ *           glossaryPlugin.getRemarkPlugin({
+ *             glossaryPath: 'glossary/glossary.json',
+ *             routePath: '/glossary',
+ *           }, { siteDir: __dirname }),
+ *         ],
+ *       },
+ *       pages: {
+ *         remarkPlugins: [
+ *           glossaryPlugin.getRemarkPlugin({
+ *             glossaryPath: 'glossary/glossary.json',
+ *             routePath: '/glossary',
+ *           }, { siteDir: __dirname }),
+ *         ],
+ *       },
+ *     }],
+ *   ],
+ *   plugins: [
+ *     ['docusaurus-plugin-glossary', {
+ *       glossaryPath: 'glossary/glossary.json',
+ *       routePath: '/glossary',
+ *     }],
+ *   ],
+ * };
+ * ```
+ *
+ * @param context - Docusaurus context
+ * @param options - Plugin options
+ * @param options.glossaryPath - Path to glossary JSON file (default: 'glossary/glossary.json')
+ * @param options.routePath - Route path for glossary page (default: '/glossary')
+ * @param options.autoLinkTerms - Legacy option, kept for compatibility but no longer used (configure remark plugin manually instead)
+ * @returns Plugin object
+ */
+export default function glossaryPlugin(context, options = {}) {
+    const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary', autoLinkTerms = true, } = options;
+    let glossaryDataCache = { terms: [] };
+    return {
+        name: 'docusaurus-plugin-glossary',
+        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: [] };
+        },
+        async contentLoaded({ content, actions }) {
+            const { createData, addRoute, setGlobalData } = actions;
+            const glossaryContent = content;
+            // Create data file that can be imported by components
+            const glossaryDataPath = await createData('glossary-data.json', JSON.stringify(glossaryContent));
+            // Create a data file for the remark plugin to access glossary terms
+            const remarkGlossaryDataPath = await createData('remark-glossary-data.json', JSON.stringify({
+                terms: glossaryContent.terms || [],
+                routePath: routePath,
+            }));
+            // Add glossary page route
+            // Compute __dirname if not already set (for webpack bundling compatibility)
+            const pluginDirname = __dirname || getDirname();
+            addRoute({
+                path: routePath,
+                component: path.join(pluginDirname, 'components/GlossaryPage.js'),
+                exact: true,
+                modules: {
+                    glossaryData: glossaryDataPath,
+                },
+            });
+            // Expose global data for runtime lookups (used by GlossaryTerm)
+            setGlobalData({
+                terms: glossaryContent.terms || [],
+                routePath,
+            });
+        },
+        getThemePath() {
+            // Compute __dirname if not already set (for webpack bundling compatibility)
+            const pluginDirname = __dirname || getDirname();
+            return path.resolve(pluginDirname, './theme');
+        },
+        getPathsToWatch() {
+            return [path.resolve(context.siteDir, glossaryPath)];
+        },
+        async postBuild({ outDir }) {
+            // You can add any post-build steps here if needed
+            console.log('Glossary plugin: Build completed');
+        },
+    };
+}
+// Export remark plugin factory for use in markdown configuration
+export const remarkPlugin = remarkGlossaryTerms;
+/**
+ * Helper function to get the configured remark plugin
+ * This can be used in docusaurus.config.js markdown configuration
+ *
+ * @param pluginOptions - Plugin options from docusaurus.config.js
+ * @param context - Context with siteDir
+ * @returns Configured remark plugin
+ */
+export function getRemarkPlugin(pluginOptions, context) {
+    const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary' } = pluginOptions;
+    const siteDir = context === null || context === void 0 ? void 0 : context.siteDir;
+    return [
+        remarkGlossaryTerms,
+        {
+            glossaryPath,
+            routePath,
+            siteDir,
+        },
+    ];
+}