docusaurus-plugin-terminology 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-10-16
+
+### Added
+
+- Zero-configuration, SSR-safe term link tooltips: the theme overrides the MDX
+  `a` component and renders term links as `<TermTooltip>`.
+- The public entry point is now a **preset** that registers a dedicated
+  `@docusaurus/plugin-content-docs` instance (id `terminology`) rendering term
+  pages at a top-level route (`/terms/` by default).
+- Option validation with descriptive error messages.
+- `docsInstance`, `sidebarLabel` and `glossarySlug` options.
+- i18n support for the new top-level layout.
+- `examples/site`: a Docusaurus demo used as an integration test, plus a GitHub
+  Pages deployment workflow.
+- CI matrix (Docusaurus `3.7`/`3.10` × React `18`/`19`).
+- TypeScript definitions for the preset and options.
+
+### Changed
+
+- Term definitions now live in a **top-level** directory (`terms/`) instead of
+  `docs/terms/`.
+- Tooltip rendering moved from a client-side DOM-manipulation module to a
+  React component rendered during SSR.
+- Package metadata: `exports`, `files`, `engines` (`node >= 18`), `sideEffects`.
+- `<Glossary />` groups by localized terms with default-locale fallback and uses
+  `@docusaurus/Link`.
+
+### Removed
+
+- The client-side `theme/tooltip.js` module (CDN tippy, `MutationObserver`,
+  polling, debug badge, history patching).
+- The `remark/term-link-transformer.js` remark plugin (replaced by the MDX `a`
+  component override).
+- Unused dependencies (`@tippyjs/react`, `unist-util-visit`).
+
+### Fixed
+
+- Tooltips no longer depend on a non-existent `extendMarkdownOptions` plugin
+  hook, which is why they previously appeared in dev but not in production.
+- Term pages no longer require `_category_.yml` hacks to stay out of the docs
+  sidebar.
+
+### Migration
+
+See the “Migrating from 0.1.x” section in the [README](./README.md#migrating-from-01x).
+
+## [0.1.0] - 2026-05-11
+
+### Added
+
+- Initial release: glossary data from `docs/terms`, tippy.js tooltips via a
+  client module, `<Glossary />` component, `hideTermsFromSidebar` option.

package/README.md

@@ -1,136 +1,95 @@
 # docusaurus-plugin-terminology
 
+Terminology & glossary support for [Docusaurus 3](https://docusaurus.io):
 
-## Overview
+- 📄 **Term pages** — each term is a Markdown/MDX file rendered as its own page.
+- 💬 **Link tooltips** — links to terms are automatically enhanced with a
+  definition tooltip. **Zero configuration**, SSR-safe (the link is in the HTML).
+- 🔤 **Glossary page** — an A–Z glossary generated from your term files.
+- 🌍 **i18n** — locale-aware terms with fallback to the default locale.
+- ⚛️ **React 18 & 19**, Docusaurus 3.7 → 3.10.
 
-Terminology/glossary plugin for [Docusaurus](https://github.com/facebook/docusaurus) 3 with:
-
-- glossary generation
-- term tooltips
-- MDX support (Built on MDX AST transformations instead of raw HTML replacement for improved Docusaurus 3 compatibility)
-- i18n support
-- Tippy.js integration
-
-This plugin is inspired by [@grnet/docusaurus-terminology](https://github.com/grnet/docusaurus-terminology). It's based on the same general concept but uses MDX remark transformations instead of webpack loader injection and uses a more robust handling of the terms' links.  
-Compatible with Docusaurus 3.x and React 18.  
-Tested with Docusaurus 3.7.0.
-
-
-## Features
+```md
+Check out [AI](/terms/ai) for more details.
+```
 
-- Define terms as Markdown files.
-- Glossary component: Automatic glossary data aggregation from Markdown term files in `docs/glossary`.
-- Tooltips on glossary links: Automatically transforms glossary links into interactive tooltip components.
-- Locale-aware glossary support: Supports multiple locales and ensures fallback to the default locale for missing terms.
-- Compatible with Docusaurus 3 + React 18
-- SSR-safe MDX integration
+renders a normal link that also shows the term's description on hover:
 
+> Check out <ins>AI</ins><sup>*</sup> *— Artificial Intelligence: the simulation
+> of human intelligence processes by machines.*
 
 ## Compatibility
 
-| Package | Version |
-|---|---|
-| Docusaurus | 3.7.0+ |
-| React | 18+ |
-| Node.js | 18+ recommended |
-
-The plugin supports `.md` and `.mdx` files.
+| Package | Supported |
+| --- | --- |
+| Docusaurus | `3.7` – `3.10` (tested against `3.10.2`) |
+| React | `18` and `19` |
+| Node.js | `18+` (Docusaurus `3.10` itself requires `20+`) |
 
+Both `.md` and `.mdx` term files are supported.
 
 ## Installation
 
-Install the plugin using npm or yarn:
-
 ```bash
 npm install docusaurus-plugin-terminology
 ```
 
-or
-
-```bash
-yarn add docusaurus-plugin-terminology
-```
-
-
-## Configuration
-
-Add the plugin to `docusaurus.config.js`:
-
-```js
-plugins: [
-  [
-    'docusaurus-plugin-terminology',
-    {
-      // options
-      termsDir: 'terms', // default: 'terms'
-      routeBasePath: '/docs/terms/', // default: '/docs/terms/'
-      hideTermsFromSidebar: true, // when true, plugin will create _category_.yml to hide individual term pages
-    }
-  ]
-],
+## Quick start
+
+The package's default export is a **preset**. Register it **after** the classic
+preset so its theme wins theme resolution (this is what makes tooltips work
+without any extra configuration):
+
+```js title="docusaurus.config.js"
+module.exports = {
+  presets: [
+    ['classic', { /* ... your options ... */ }],
+    [
+      'docusaurus-plugin-terminology',
+      {
+        termsDir: 'terms',        // top-level directory, default: 'terms'
+        routeBasePath: '/terms/', // public URL, default: '/terms/'
+      },
+    ],
+  ],
+};
 ```
 
----
-
-## Usage
-
-### Defining terms
-
-Create a `terms` directory within `docs` (the plugin default).
-
-Add Markdown files for your terms in that directory.  
-Structure example:
+Then create a `terms/` directory at the root of your site:
 
 ```text
-docs/
-├── terms/           # terms definitions
+.
+├── docs/
+│   └── glossary.md   # a page rendering <Glossary />
+├── terms/
 │   ├── ai.md
 │   ├── css.md
-│   ├── ftp.md
-│   ├── html.md
-│   └── ...
-└── terms.md         # glossary page (id: glossary)
+│   └── ftp.md
+└── docusaurus.config.js
 ```
 
-
-#### Example Term File
-
-Each file should contain metadata in the frontmatter:
-
-```yaml
+```md title="terms/ai.md"
 ---
-title: AI - »Artificial Intelligence«
-description: Intelligence of machines.
+title: AI
+description: Artificial Intelligence — the simulation of human intelligence processes by machines.
 ---
-```
-```markdown
-The capability of computational systems to perform tasks typically associated with human intelligence, such as learning, reasoning, problem-solving, perception, and decision-making. It is a field of research in engineering, mathematics and computer science that develops and studies methods and software that enable machines to perceive their environment and use learning and intelligence to take actions that maximize their chances of achieving defined goals.  
-
-*From [Artificial intelligence - Wikipedia](https://en.wikipedia.org/wiki/Artificial_intelligence#Techniques)*
 
+Artificial intelligence (AI) is the simulation of human intelligence processes
+by computer systems.
 ```
 
-### Linking terms
-
-Link to terms in your Markdown files using the `/docs/terms/TERM_SLUG` format (or adjust to your `termsDir`).  
-Example:
+Term pages are now available at `/terms/ai`, `/terms/css`, … and linking to
+them from anywhere in your Markdown shows a tooltip:
 
-```markdown
-[AI](/docs/terms/ai)
+```md
+See [AI](/terms/ai) and [CSS](/terms/css).
 ```
 
-The plugin will automatically transform these links into tooltips.
-
-
-### Glossary Page
+## Glossary page
 
-The plugin provides a `Glossary` component that displays all glossary terms grouped alphabetically. You can use this component in your custom pages.
+Add a docs page (anywhere in your `docs/`) that renders the glossary component:
 
-#### Create a glossary page
-
-E.g. `glossary.md` (the file name doesn't matter)
-
-```markdown
+```mdx title="docs/glossary.md"
 ---
 id: glossary
 title: Glossary
@@ -141,73 +100,125 @@ import Glossary from '@theme/Glossary';
 <Glossary />
 ```
 
-### i18n
+`<Glossary />` displays every term (grouped A–Z) with its description and a link
+to its term page.
 
-Localized term definitions can be placed in:
+## Options
 
-```text
-i18n/de/docusaurus-plugin-content-docs/current/terms/
-```
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `termsDir` | `string` | `'terms'` | Directory containing the term files, relative to the site root. |
+| `routeBasePath` | `string` | `'/terms/'` | Public URL prefix of the generated term pages, also used to detect term links. |
+| `docsInstance` | `boolean` | `true` | Register a dedicated docs instance for the term pages. Set to `false` for [legacy mode](#legacy-mode). |
+| `hideTermsFromSidebar` | `boolean` | `false` | Legacy mode only: write a `_category_.yml` hiding the term docs from the main sidebar. |
+| `sidebarLabel` | `string` | `'Glossary'` | Legacy mode only: label of the hidden sidebar category. |
+| `glossarySlug` | `string` | `'glossary'` | Legacy mode only: doc id of the glossary page the hidden category links to. |
 
+Invalid options throw a descriptive error at build time.
 
 ## How it works
 
-1. The plugin scans `docs/terms` (or the directory configured via `termsDir`)
-2. Term metadata is extracted from frontmatter
-3. Markdown links matching `/docs/terms/*` (or matching your `routeBasePath`) are transformed into MDX tooltip components
-4. Generates a static glossary JSON data source for tooltip rendering
-5. Glossary data is exposed globally to Docusaurus theme components
+1. A dedicated `@docusaurus/plugin-content-docs` instance (id `terminology`)
+   renders the files in `termsDir` at `routeBasePath` — no sidebar, no docs
+   ordering surprises.
+2. The terminology plugin reads the same files and exposes a locale-aware
+   glossary (name + short description) as global plugin data.
+3. The terminology theme overrides the MDX `a` component. A normal Markdown link
+   is delegated to Docusaurus, while a link pointing at `routeBasePath` is
+   rendered as `<TermTooltip>` with the glossary description. Because this
+   happens at render time, the link is part of the server-rendered HTML and no
+   remark plugin, `MDXComponents` swizzle, or DOM scanning is required.
+
+> **Why register the preset after `classic`?** Docusaurus resolves
+> `@theme/MDXComponents/A` by theme priority. Listing the terminology preset
+> last makes its theme the highest-priority provider, which is what lets it
+> override the link component.
 
+## Descriptions
 
-### Internal Architecture
-Markdown links
-↓
-remark plugin transformation
-↓
-<TermTooltip />
-↓
-MDX component mapping
-↓
-Tippy.js tooltip rendering
+The tooltip text is taken from `description` in the frontmatter when present,
+otherwise from the first paragraph of the term body (Markdown is stripped and
+the result is truncated). `summary` and `excerpt` are also accepted as
+frontmatter aliases.
 
+## i18n
 
-### Styling
+Localized term files are picked up automatically. Supported locations:
 
-Override tooltip styles via CSS.
+```text
+i18n/<locale>/<termsDir>/                                   # e.g. i18n/de/terms/ai.md
+i18n/<locale>/docusaurus-plugin-content-docs-terminology/current/
+```
 
+Missing localized terms fall back to the default locale, so you only translate
+what you need.
 
-## File Structure
+## Styling
 
-The plugin's file structure is as follows:
+Term links use a dotted underline and a tippy.js tooltip. Override the look with
+plain CSS:
 
+```css
+.tippy-box[data-theme~='terminology'] {
+  /* your styles */
+}
 ```
-docusaurus-plugin-terminology
-    ├── remark
-    │   └── term-link-transformer.js
-    ├── theme
-    │   ├── Glossary.jsx
-    │   └── tooltip.js
-    ├── index.js
-    ├── LICENSE
-    └── README.md
+
+## Legacy mode (`0.1.x` layout)
+
+If your terms live **inside** `docs/` (e.g. `docs/terms/ai.md`) you can keep that
+layout:
+
+```js
+presets: [
+  ['classic', { /* ... */ }],
+  [
+    'docusaurus-plugin-terminology',
+    {
+      docsInstance: false,
+      termsDir: 'terms',          // -> docs/terms
+      routeBasePath: '/docs/terms/',
+      hideTermsFromSidebar: true, // hide the term docs in the sidebar
+    },
+  ],
+],
 ```
 
-- `remark/term-link-transformer.js`: Transforms glossary term links in Markdown files into `TermTooltip` components.
-- `theme/Glossary.jsx`: Renders the glossary page.
-- `theme/tooltip.js`: Handles tooltips for glossary terms.
-- `index.js`: Main plugin entry point.
+## Migrating from `0.1.x`
 
+`0.2.0` is a breaking release:
 
-## Contributing
+1. **Registration changed**: the package is now a preset (registered in
+   `presets`) instead of a plugin (in `plugins`).
+2. **Terms moved to the top level**: move `docs/terms/` to `terms/` and set
+   `routeBasePath: '/terms/'`. (Or keep the old layout with `docsInstance: false`.)
+3. **Links changed**: update links from `/docs/terms/<slug>` to `/terms/<slug>`.
+4. **Tooltips are zero-config**: the fragile client-side `theme/tooltip.js`
+   module was removed — nothing to configure.
+
+## Development
 
-Contributions are welcome! Feel free to open issues or submit pull requests to improve the plugin.
+```bash
+npm install          # install dev dependencies
+npm test             # unit tests (Jest)
 
+cd examples/site
+npm install
+npm start            # http://localhost:3000/docusaurus-plugin-terminology/
+npm run build        # production build (regression check)
+```
 
-## License
+The demo site in [`examples/site`](./examples/site) is the integration test: it
+builds on every CI run against a Docusaurus × React matrix.
 
-This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
+## Contributing
+
+Issues and pull requests are welcome.
+
+## License
 
+MIT — see [LICENSE](./LICENSE).
 
 ## Acknowledgments
 
-This plugin is inspired by [@grnet/docusaurus-terminology](https://github.com/grnet/docusaurus-terminology) and aims to provide a more robust and modern implementation.
+Inspired by [@grnet/docusaurus-terminology](https://github.com/grnet/docusaurus-terminology).

package/index.js

@@ -1,181 +1,81 @@
-// docusaurus-plugin-terminology/index.js
-const path = require('path');
-const fs = require('fs');
-const matter = require('gray-matter');
+'use strict';
 
-module.exports = function (context, options = {}) {
+/**
+ * docusaurus-plugin-terminology (preset)
+ *
+ * Public entry point. Registers:
+ *
+ *   1. a dedicated `@docusaurus/plugin-content-docs` instance rendering the
+ *      term definitions under a top-level route (default `/terms/`);
+ *   2. the terminology content plugin (glossary data + legacy sidebar hiding);
+ *   3. the terminology theme (MDX link tooltips + `<Glossary />`).
+ *
+ * Usage (order matters — keep it *after* the classic preset so that the
+ * terminology theme wins the theme resolution):
+ *
+ * ```js
+ * presets: [
+ *   ['classic', { ... }],
+ *   ['docusaurus-plugin-terminology', { termsDir: 'terms', routeBasePath: '/terms/' }],
+ * ],
+ * ```
+ */
 
-    // Provide sensible defaults and read hide flag
-    options = Object.assign(
-        {
-            termsDir: 'terms',
-            routeBasePath: '/docs/terms/',
-            hideTermsFromSidebar: false,
-        },
-        options || {}
-    );
+const path = require('path');
+const terminologyPlugin = require('./plugin');
+const terminologyTheme = require('./theme-plugin');
+const {normalizeOptions} = require('./src/options');
 
-    const termsDir = options.termsDir || 'terms';
-    const routeBasePath = options.routeBasePath || '/docs/terms/';
-    const hideTermsFromSidebar = options.hideTermsFromSidebar === true;
+const TERMS_DOCS_INSTANCE_ID = 'terminology';
+const CONTENT_DOCS_PLUGIN = '@docusaurus/plugin-content-docs';
 
-    //console.log('[plugin] docusaurus-plugin-terminology loaded');
-    return {
-        name: 'docusaurus-plugin-terminology',
-        
-        extendMarkdownOptions(mdOptions) {
-            mdOptions.remarkPlugins = mdOptions.remarkPlugins || [];
-            mdOptions.remarkPlugins.push([
-                require('./remark/term-link-transformer'),
-                {
-                    termsDir,
-                    routeBasePath,
-                },
-            ]);
-            //console.log('[plugin] extendMarkdownOptions: registered termLinkTransformer');
-        },
-        
-        /**
-         * Optionally write a _category_.yml into the terms docs directory (and per-locale equivalents)
-         * so that the terms directory is represented by a single category entry that can be hidden
-         * (className: hidden). This prevents the individual generated term files from showing up
-         * in the main docs sidebar.
-         */
-        async loadContent() {
-            if (!hideTermsFromSidebar) return null;
+function toDocsRouteBasePath(routeBasePath) {
+  return String(routeBasePath).replace(/^\/+|\/+$/g, '');
+}
 
-            const CATEGORY_FILENAME = '_category_.yml';
-            const makeCategoryYaml = (label = 'Glossar') => `label: ${label}
-className: hidden
-collapsed: true
-link:
-  type: doc
-  id: glossary
-`;
+/**
+ * @param {import('@docusaurus/types').LoadContext} context
+ * @param {object} [options]
+ * @returns {import('@docusaurus/types').Preset}
+ */
+function terminologyPreset(context, options = {}) {
+  const normalized = normalizeOptions(options);
 
-            const writeIfMissing = (docsDir) => {
-                try {
-                    if (!fs.existsSync(docsDir)) return;
-                    const catPath = path.join(docsDir, CATEGORY_FILENAME);
-                    if (fs.existsSync(catPath)) {
-                        // Respect an existing file; do not overwrite
-                        return;
-                    }
-                    fs.writeFileSync(catPath, makeCategoryYaml(), { encoding: 'utf8' });
-                    console.info(`[docusaurus-plugin-terminology] wrote ${CATEGORY_FILENAME} to ${docsDir}`);
-                } catch (err) {
-                    // Non-fatal: warn and continue
-                    console.warn(`[docusaurus-plugin-terminology] failed to write ${CATEGORY_FILENAME} to ${docsDir}: ${err.message}`);
-                }
-            };
+  const plugins = [];
 
-            // default locale docs dir
-            const defaultDocsDir = path.resolve(context.siteDir, `docs/${termsDir}`);
-            writeIfMissing(defaultDocsDir);
+  if (normalized.docsInstance) {
+    plugins.push([
+      CONTENT_DOCS_PLUGIN,
+      {
+        id: TERMS_DOCS_INSTANCE_ID,
+        path: normalized.termsDir,
+        routeBasePath: toDocsRouteBasePath(normalized.routeBasePath),
+        // The term pages are standalone: no sidebar at all for this instance.
+        sidebarPath: false,
+        breadcrumbs: false,
+        editUrl: undefined,
+      },
+    ]);
+  }
 
-            // localized docs dirs (if i18n present)
-            const { i18n } = context || {};
-            if (i18n && Array.isArray(i18n.locales)) {
-                for (const locale of i18n.locales) {
-                    if (locale === i18n.defaultLocale) continue;
-                    const localizedDocsDir = path.resolve(
-                        context.siteDir,
-                        `i18n/${locale}/docusaurus-plugin-content-docs/current/${termsDir}`
-                    );
-                    writeIfMissing(localizedDocsDir);
-                }
-            }
+  plugins.push([terminologyPlugin, normalized]);
 
-            return null;
-        },
-        
-        /**
-         * Called when content has been loaded. 
-         * Processes glossary terms data for different locales and generates a glossary JSON file.
-         * @param {Object} context - The context object containing siteDir, i18n, and actions.
-         */
-        async contentLoaded({ actions }) {
-            const { siteDir, i18n } = context;
-            const { defaultLocale, locales } = i18n;
-            const { setGlobalData, createData } = actions;
-            
-            const termsData = {};
-            
-            for (const locale of locales) {
-            const docsDir = locale === defaultLocale
-            ? path.resolve(siteDir, `docs/${termsDir}`)
-            : path.resolve(
-                siteDir,
-                `i18n/${locale}/docusaurus-plugin-content-docs/current/${termsDir}`
-            );
-            
-            if (!fs.existsSync(docsDir)) continue;
-            
-            const termFiles = fs.readdirSync(docsDir).filter((f) => (f.endsWith('.md') || f.endsWith('.mdx')) && f !== 'index.md');
-            
-            const termsArray = [];
-            
-            for (const filename of termFiles) {
-                const slug = filename.replace(/\.mdx?$/, '');
-                const filepath = path.join(docsDir, filename);
-                const fileContent = fs.readFileSync(filepath, 'utf-8');
-                const { data, content } = matter(fileContent);
-                
-                termsArray.push({
-                slug,
-                name: data.title || slug,
-                description: data.description || content.trim().split('\n')[0],
-                });
-            }
-            
-            // Sort termsArray alphabetically by name
-            termsArray.sort((a, b) => a.name.localeCompare(b.name));
-            
-            // Convert sorted array back to object
-            termsData[locale] = termsArray.reduce((acc, term) => {
-                acc[term.slug] = {
-                name: term.name,
-                description: term.description,
-                };
-                return acc;
-            }, {});
-            }
-            
-            // Fallback: fill in missing terms for other locales using default locale
-            for (const locale of Object.keys(termsData)) {
-                if (locale === defaultLocale) continue;
-                for (const [slug, entry] of Object.entries(termsData[defaultLocale] || {})) {
-                    if (!termsData[locale]?.[slug]) {
-                        if (!termsData[locale]) termsData[locale] = {};
-                        termsData[locale][slug] = entry;
-                    }
-                }
-            }
+  return {
+    plugins,
+    // Declared as a preset *theme* on purpose: it is evaluated after the
+    // classic theme, which is what lets us override `@theme/MDXComponents/A`.
+    themes: [terminologyTheme],
+  };
+}
 
-            //console.log('[plugin] termsData:', termsData);
-            //console.log('Current locale:', i18n.currentLocale);
+module.exports = terminologyPreset;
+module.exports.default = terminologyPreset;
+module.exports.terminologyPreset = terminologyPreset;
 
-            // Write static glossary JSON file (default locale only)
-            const outputJson = JSON.stringify(termsData[defaultLocale] || {}, null, 2);
-            const glossaryDataPath = await createData('glossary.json', outputJson);
-            //console.log('[plugin] glossary.json generated at:', glossaryDataPath);
-            //console.log('[plugin] setGlobalData terms:', termsData);
+// Named exports for advanced/legacy use.
+module.exports.plugin = terminologyPlugin;
+module.exports.theme = terminologyTheme;
 
-            // Expose for use in components
-            setGlobalData({
-                terms: termsData,
-                glossaryDataPath,
-                routeBasePath,
-                termsDir,
-            });
-        },
-        
-        getThemePath() {
-            return path.resolve(__dirname, './theme');
-        },
-        
-        getClientModules() {
-            return [path.resolve(__dirname, './theme/tooltip.js')];
-        },
-    };
-};
+// Handy for tooling/tests.
+module.exports.TERMS_DOCS_INSTANCE_ID = TERMS_DOCS_INSTANCE_ID;
+module.exports.resolveThemePath = () => path.resolve(__dirname, 'theme');