docusaurus-plugin-glossary 2.0.2 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 mcclowes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -28,58 +28,36 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
    npm install docusaurus-plugin-glossary
    ```
 
-2. **Add to your `docusaurus.config.js`:**
+2. **Use the preset in your `docusaurus.config.js`:**
 
    ```javascript
-   const glossaryPlugin = require('docusaurus-plugin-glossary');
-
    module.exports = {
-     // ... other config
      presets: [
        [
-         '@docusaurus/preset-classic',
+         'docusaurus-plugin-glossary/preset',
          {
+           // Glossary configuration
+           glossary: {
+             glossaryPath: 'glossary/glossary.json',
+             routePath: '/glossary',
+           },
+           // Standard Docusaurus preset-classic options
            docs: {
-             // Add the remark plugin to enable auto-linking in docs
-             remarkPlugins: [
-               glossaryPlugin.getRemarkPlugin(
-                 {
-                   glossaryPath: 'glossary/glossary.json',
-                   routePath: '/glossary',
-                 },
-                 { siteDir: __dirname }
-               ),
-             ],
+             sidebarPath: './sidebars.js',
            },
-           pages: {
-             // Add the remark plugin to enable auto-linking in pages
-             remarkPlugins: [
-               glossaryPlugin.getRemarkPlugin(
-                 {
-                   glossaryPath: 'glossary/glossary.json',
-                   routePath: '/glossary',
-                 },
-                 { siteDir: __dirname }
-               ),
-             ],
+           blog: {
+             showReadingTime: true,
+           },
+           theme: {
+             customCss: './src/css/custom.css',
            },
          },
        ],
      ],
-     plugins: [
-       [
-         'docusaurus-plugin-glossary',
-         {
-           glossaryPath: 'glossary/glossary.json', // Path to your glossary file
-           routePath: '/glossary', // URL path for glossary page
-         },
-       ],
-     ],
-     // ... other config
    };
    ```
 
-   **Note:** You need to configure the remark plugin in both the plugin AND the preset (for docs/pages) to enable auto-linking of terms.
+   **That's it!** The preset automatically configures the glossary plugin and remark plugin for you.
 
 3. **Create your glossary file at `glossary/glossary.json`:**
 
@@ -161,7 +139,41 @@ Create a JSON file at `glossary/glossary.json` (or your configured path) in your
 
 ### Step 2: Configure the Plugin
 
-Add the plugin to your `docusaurus.config.js`:
+#### Option A: Using the Preset (Recommended)
+
+The easiest way to configure the plugin is using the preset:
+
+```javascript
+module.exports = {
+  presets: [
+    [
+      'docusaurus-plugin-glossary/preset',
+      {
+        glossary: {
+          glossaryPath: 'glossary/glossary.json',
+          routePath: '/glossary',
+        },
+        // All standard preset-classic options work here
+        docs: {
+          sidebarPath: './sidebars.js',
+        },
+        blog: {
+          showReadingTime: true,
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      },
+    ],
+  ],
+};
+```
+
+The preset automatically configures both the glossary plugin and the remark plugin for automatic term detection.
+
+#### Option B: Manual Configuration (Advanced)
+
+If you need more control or want to use the plugin alongside the classic preset separately:
 
 ```javascript
 const glossaryPlugin = require('docusaurus-plugin-glossary');
@@ -202,16 +214,14 @@ module.exports = {
     [
       'docusaurus-plugin-glossary',
       {
-        glossaryPath: 'glossary/glossary.json', // Path to your glossary file
-        routePath: '/glossary', // URL path for the glossary page
+        glossaryPath: 'glossary/glossary.json',
+        routePath: '/glossary',
       },
     ],
   ],
 };
 ```
 
-**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.
-
 **Alternative: Using remarkPlugin directly**
 
 You can also use the `remarkPlugin` export directly if you prefer:
@@ -258,16 +268,19 @@ This plugin uses a **hybrid approach** combining build-time transformation and r
 ### Build-Time: Remark Plugin
 
 The remark plugin automatically detects glossary terms in your markdown and:
+
 1. Transforms plain text terms into `<GlossaryTerm>` JSX components
 2. Automatically injects the necessary import statement (`import GlossaryTerm from '@theme/GlossaryTerm';`)
 3. This happens during the MDX compilation, before React renders anything
 
 **No manual imports needed!** When you write:
+
 ```markdown
 Our API uses REST principles.
 ```
 
 The remark plugin transforms it to:
+
 ```jsx
 import GlossaryTerm from '@theme/GlossaryTerm';
 
@@ -277,6 +290,7 @@ Our <GlossaryTerm term="API">API</GlossaryTerm> uses <GlossaryTerm term="REST">R
 ### Runtime: Client Modules
 
 The plugin uses Docusaurus's `getClientModules()` API to automatically load client-side code on every page. This ensures:
+
 - Glossary term functionality is available globally without configuration
 - Components initialize correctly on each route change
 - No performance impact from manual module loading
@@ -284,6 +298,7 @@ The plugin uses Docusaurus's `getClientModules()` API to automatically load clie
 ### Theme Components
 
 The `GlossaryTerm` component is provided via the theme system (`@theme/GlossaryTerm`), making it:
+
 - Available to all MDX files through automatic imports
 - Swizzlable for custom styling and behavior
 - Accessible to both the remark plugin and manual usage
@@ -543,6 +558,7 @@ npm run build
 ```
 
 This will:
+
 1. Compile TypeScript (`src/index.ts`) to JavaScript (`dist/index.js`)
 2. Copy JavaScript, CSS, and test files from `src/` to `dist/`
 

package/dist/preset.js

@@ -0,0 +1,146 @@
+import glossaryPlugin, { getRemarkPlugin } from './index.js';
+/**
+ * Docusaurus Glossary Preset
+ *
+ * A preset that extends @docusaurus/preset-classic with automatic glossary functionality.
+ * This preset automatically configures the remark plugin for docs and pages, so you don't
+ * need to manually add it to remarkPlugins.
+ *
+ * @example
+ * ```javascript
+ * export default {
+ *   presets: [
+ *     [
+ *       'docusaurus-plugin-glossary/preset',
+ *       {
+ *         // Glossary options
+ *         glossary: {
+ *           glossaryPath: 'glossary/glossary.json',
+ *           routePath: '/glossary',
+ *         },
+ *         // Classic preset options
+ *         docs: {
+ *           sidebarPath: './sidebars.js',
+ *         },
+ *         blog: {
+ *           showReadingTime: true,
+ *         },
+ *         theme: {
+ *           customCss: './src/css/custom.css',
+ *         },
+ *       },
+ *     ],
+ *   ],
+ * };
+ * ```
+ *
+ * @param context - Docusaurus context
+ * @param options - Preset options including glossary and classic preset options
+ * @returns Preset configuration
+ */
+export default function preset(context, options = {}) {
+    // Explicitly extract glossary and any Docusaurus-added properties that shouldn't go to classic preset
+    const { glossary = {}, id, ...restOptions } = options;
+    // Extract only valid classic preset options
+    const { docs, blog, pages, theme, gtag, googleAnalytics, googleTagManager, sitemap, debug, } = restOptions;
+    // Build classic options object with only defined properties
+    const classicOptions = {};
+    if (docs !== undefined)
+        classicOptions.docs = docs;
+    if (blog !== undefined)
+        classicOptions.blog = blog;
+    if (pages !== undefined)
+        classicOptions.pages = pages;
+    if (theme !== undefined)
+        classicOptions.theme = theme;
+    if (gtag !== undefined)
+        classicOptions.gtag = gtag;
+    if (googleAnalytics !== undefined)
+        classicOptions.googleAnalytics = googleAnalytics;
+    if (googleTagManager !== undefined)
+        classicOptions.googleTagManager = googleTagManager;
+    if (sitemap !== undefined)
+        classicOptions.sitemap = sitemap;
+    if (debug !== undefined)
+        classicOptions.debug = debug;
+    const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary', } = glossary;
+    // Get the remark plugin configuration
+    const remarkPlugin = getRemarkPlugin({ glossaryPath, routePath }, { siteDir: context.siteDir });
+    // Extend docs configuration with glossary remark plugin
+    const docsConfig = classicOptions.docs || {};
+    const docsRemarkPlugins = docsConfig.remarkPlugins || [];
+    const extendedDocsConfig = {
+        ...docsConfig,
+        remarkPlugins: [...docsRemarkPlugins, remarkPlugin],
+    };
+    // Extend pages configuration with glossary remark plugin
+    const pagesConfig = classicOptions.pages || {};
+    const pagesRemarkPlugins = pagesConfig.remarkPlugins || [];
+    const extendedPagesConfig = {
+        ...pagesConfig,
+        remarkPlugins: [...pagesRemarkPlugins, remarkPlugin],
+    };
+    // Extend blog configuration with glossary remark plugin (optional)
+    const blogConfig = classicOptions.blog;
+    let extendedBlogConfig = blogConfig;
+    if (blogConfig && blogConfig !== false) {
+        const blogRemarkPlugins = typeof blogConfig === 'object' ? blogConfig.remarkPlugins || [] : [];
+        extendedBlogConfig =
+            typeof blogConfig === 'object'
+                ? {
+                    ...blogConfig,
+                    remarkPlugins: [...blogRemarkPlugins, remarkPlugin],
+                }
+                : blogConfig;
+    }
+    // Build the final classic preset options
+    const finalClassicOptions = {};
+    if (extendedDocsConfig !== undefined)
+        finalClassicOptions.docs = extendedDocsConfig;
+    if (extendedBlogConfig !== undefined)
+        finalClassicOptions.blog = extendedBlogConfig;
+    if (extendedPagesConfig !== undefined)
+        finalClassicOptions.pages = extendedPagesConfig;
+    if (theme !== undefined)
+        finalClassicOptions.theme = theme;
+    if (gtag !== undefined)
+        finalClassicOptions.gtag = gtag;
+    if (googleAnalytics !== undefined)
+        finalClassicOptions.googleAnalytics = googleAnalytics;
+    if (googleTagManager !== undefined)
+        finalClassicOptions.googleTagManager = googleTagManager;
+    if (sitemap !== undefined)
+        finalClassicOptions.sitemap = sitemap;
+    if (debug !== undefined)
+        finalClassicOptions.debug = debug;
+    const plugins = [
+        // Add the glossary plugin first
+        function glossaryPluginWrapper(context) {
+            return glossaryPlugin(context, glossary);
+        },
+    ];
+    // Add classic preset plugins individually
+    if (extendedDocsConfig)
+        plugins.push(['@docusaurus/plugin-content-docs', extendedDocsConfig]);
+    if (extendedBlogConfig && extendedBlogConfig !== false)
+        plugins.push(['@docusaurus/plugin-content-blog', extendedBlogConfig]);
+    if (extendedPagesConfig)
+        plugins.push(['@docusaurus/plugin-content-pages', extendedPagesConfig]);
+    if (gtag)
+        plugins.push(['@docusaurus/plugin-google-gtag', gtag]);
+    if (googleAnalytics)
+        plugins.push(['@docusaurus/plugin-google-analytics', googleAnalytics]);
+    if (googleTagManager)
+        plugins.push(['@docusaurus/plugin-google-tag-manager', googleTagManager]);
+    if (sitemap !== false)
+        plugins.push(['@docusaurus/plugin-sitemap', sitemap || {}]);
+    if (debug)
+        plugins.push(['@docusaurus/plugin-debug', {}]);
+    return {
+        themes: [
+            // Return classic theme - use string instead of require.resolve so it resolves from user's node_modules
+            '@docusaurus/theme-classic',
+        ],
+        plugins,
+    };
+}

package/dist/remark/glossary-terms.js

@@ -37,7 +37,7 @@ export default function remarkGlossaryTerms({
 
       // Check cache first to avoid repeated file reads
       const cached = glossaryCache.get(glossaryFilePath);
-      if (cached && (now - cached.loadedAt) < CACHE_TTL) {
+      if (cached && now - cached.loadedAt < CACHE_TTL) {
         glossaryTerms = cached.terms;
       } else {
         // Cache miss or expired - load from file synchronously
@@ -56,7 +56,9 @@ export default function remarkGlossaryTerms({
 
           // Log only once per file (when cache is first populated)
           if (!cached && process.env.NODE_ENV !== 'production') {
-            console.log(`[glossary-plugin] Loaded ${glossaryTerms.length} terms from ${glossaryPath}`);
+            console.log(
+              `[glossary-plugin] Loaded ${glossaryTerms.length} terms from ${glossaryPath}`
+            );
           }
         } else {
           // File doesn't exist - cache empty result to avoid repeated checks
@@ -70,7 +72,10 @@ export default function remarkGlossaryTerms({
         }
       }
     } catch (error) {
-      console.warn(`[glossary-plugin] Failed to load glossary from ${glossaryPath}:`, error.message);
+      console.warn(
+        `[glossary-plugin] Failed to load glossary from ${glossaryPath}:`,
+        error.message
+      );
       // Cache the error to avoid repeated attempts
       if (glossaryPath && siteDir) {
         const glossaryFilePath = path.resolve(siteDir, glossaryPath);
@@ -315,10 +320,11 @@ export default function remarkGlossaryTerms({
       // Check for existing import
       const hasImport =
         Array.isArray(tree.children) &&
-        tree.children.some(n =>
-          n.type === 'mdxjsEsm' &&
-          (n.value?.includes('@theme/GlossaryTerm') ||
-            n.data?.estree?.body?.some(s => s.source?.value === '@theme/GlossaryTerm'))
+        tree.children.some(
+          n =>
+            n.type === 'mdxjsEsm' &&
+            (n.value?.includes('@theme/GlossaryTerm') ||
+              n.data?.estree?.body?.some(s => s.source?.value === '@theme/GlossaryTerm'))
         );
 
       if (!hasImport) {

package/dist/theme/GlossaryTerm/styles.module.css

@@ -10,7 +10,7 @@
   border-bottom-color: color-mix(in srgb, var(--ifm-font-color-base) 20%, transparent);
   cursor: help;
   transition: all 0.2s;
-} 
+}
 
 .glossaryTerm:hover {
   color: var(--ifm-color-primary-dark);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-glossary",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,11 @@
       "require": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./preset": {
+      "import": "./dist/preset.js",
+      "require": "./dist/preset.js",
+      "default": "./dist/preset.js"
+    },
     "./remark/glossary-terms": {
       "import": "./dist/remark/glossary-terms.js",
       "require": "./dist/remark/glossary-terms.js",
@@ -27,6 +32,8 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
     "example:start": "npm --prefix examples/docusaurus-v3 run start",
     "example:build": "npm --prefix examples/docusaurus-v3 run build",
     "example:serve": "npm --prefix examples/docusaurus-v3 run serve",
@@ -74,6 +81,7 @@
     "@babel/preset-typescript": "^7.28.5",
     "@docusaurus/tsconfig": "^3.9.2",
     "@docusaurus/types": "^3.9.2",
+    "@playwright/test": "^1.56.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",