docusaurus-plugin-terminology 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Jürgen Schilke.
+
+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

@@ -0,0 +1,213 @@
+# docusaurus-plugin-terminology
+
+
+## Overview
+
+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
+
+- 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
+
+
+## Compatibility
+
+| Package | Version |
+|---|---|
+| Docusaurus | 3.7.0+ |
+| React | 18+ |
+| Node.js | 18+ recommended |
+
+The plugin supports `.md` and `.mdx` files.
+
+
+## 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
+    }
+  ]
+],
+```
+
+---
+
+## Usage
+
+### Defining terms
+
+Create a `terms` directory within `docs` (the plugin default).
+
+Add Markdown files for your terms in that directory.  
+Structure example:
+
+```text
+docs/
+├── terms/           # terms definitions
+│   ├── ai.md
+│   ├── css.md
+│   ├── ftp.md
+│   ├── html.md
+│   └── ...
+└── terms.md         # glossary page (id: glossary)
+```
+
+
+#### Example Term File
+
+Each file should contain metadata in the frontmatter:
+
+```yaml
+---
+title: AI - »Artificial Intelligence«
+description: Intelligence of 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)*
+
+```
+
+### Linking terms
+
+Link to terms in your Markdown files using the `/docs/terms/TERM_SLUG` format (or adjust to your `termsDir`).  
+Example:
+
+```markdown
+[AI](/docs/terms/ai)
+```
+
+The plugin will automatically transform these links into tooltips.
+
+
+### Glossary Page
+
+The plugin provides a `Glossary` component that displays all glossary terms grouped alphabetically. You can use this component in your custom pages.
+
+#### Create a glossary page
+
+E.g. `glossary.md` (the file name doesn't matter)
+
+```markdown
+---
+id: glossary
+title: Glossary
+---
+
+import Glossary from '@theme/Glossary';
+
+<Glossary />
+```
+
+### i18n
+
+Localized term definitions can be placed in:
+
+```text
+i18n/de/docusaurus-plugin-content-docs/current/terms/
+```
+
+
+## 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
+
+
+### Internal Architecture
+Markdown links
+↓
+remark plugin transformation
+↓
+<TermTooltip />
+↓
+MDX component mapping
+↓
+Tippy.js tooltip rendering
+
+
+### Styling
+
+Override tooltip styles via CSS.
+
+
+## File Structure
+
+The plugin's file structure is as follows:
+
+```
+docusaurus-plugin-terminology
+    ├── remark
+    │   └── term-link-transformer.js
+    ├── theme
+    │   ├── Glossary.jsx
+    │   └── tooltip.js
+    ├── index.js
+    ├── LICENSE
+    └── README.md
+```
+
+- `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.
+
+
+## Contributing
+
+Contributions are welcome! Feel free to open issues or submit pull requests to improve the plugin.
+
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
+
+
+## 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.

package/index.js

@@ -0,0 +1,181 @@
+// docusaurus-plugin-terminology/index.js
+const path = require('path');
+const fs = require('fs');
+const matter = require('gray-matter');
+
+module.exports = function (context, options = {}) {
+
+    // Provide sensible defaults and read hide flag
+    options = Object.assign(
+        {
+            termsDir: 'terms',
+            routeBasePath: '/docs/terms/',
+            hideTermsFromSidebar: false,
+        },
+        options || {}
+    );
+
+    const termsDir = options.termsDir || 'terms';
+    const routeBasePath = options.routeBasePath || '/docs/terms/';
+    const hideTermsFromSidebar = options.hideTermsFromSidebar === true;
+
+    //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;
+
+            const CATEGORY_FILENAME = '_category_.yml';
+            const makeCategoryYaml = (label = 'Glossar') => `label: ${label}
+className: hidden
+collapsed: true
+link:
+  type: doc
+  id: glossary
+`;
+
+            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}`);
+                }
+            };
+
+            // default locale docs dir
+            const defaultDocsDir = path.resolve(context.siteDir, `docs/${termsDir}`);
+            writeIfMissing(defaultDocsDir);
+
+            // 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);
+                }
+            }
+
+            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;
+                    }
+                }
+            }
+
+            //console.log('[plugin] termsData:', termsData);
+            //console.log('Current locale:', i18n.currentLocale);
+
+            // 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);
+
+            // 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')];
+        },
+    };
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "docusaurus-plugin-terminology",
+  "version": "0.1.0",
+  "description": "Terminology and glossary plugin for Docusaurus 3",
+  "main": "index.js",
+  "license": "MIT",
+  "keywords": [
+    "docusaurus",
+    "docusaurus-plugin",
+    "glossary",
+    "terminology",
+    "tooltip",
+    "mdx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schilke/docusaurus-plugin-terminology.git"
+  },
+  "bugs": {
+    "url": "https://github.com/schilke/docusaurus-plugin-terminology/issues"
+  },
+  "homepage": "https://github.com/schilke/docusaurus-plugin-terminology#readme",
+  "peerDependencies": {
+    "@docusaurus/core": "^3.0.0",
+    "@docusaurus/preset-classic": "^3.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@tippyjs/react": "^4.2.6",
+    "gray-matter": "^4.0.3",
+    "unist-util-visit": "^5.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0",
+    "memfs": "^3.4.13"
+  },
+  "scripts": {
+    "test": "jest --color"
+  }
+  ,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/remark/term-link-transformer.js

@@ -0,0 +1,64 @@
+/**
+ * Transforms links to terms in Docusaurus MDX files
+ * to use a custom TermTooltip component.
+ * /docusaurus-plugin-terminology/remark/term-link-transformer.js
+ */
+
+const { visit } = require('unist-util-visit');
+
+/**
+ * Transforms links to glossary terms in the tree to MDX JSX elements.
+ * @returns {Function} A function that transforms links in the tree to MDX JSX elements.
+ */
+function termLinkTransformer(options = {}) {
+
+  const routeBasePath =
+    options.routeBasePath || '/docs/terms/';
+  return (tree, file) => {
+    visit(tree, 'link', (node, index, parent) => {
+      const href = node.url || '';
+
+      // Match links like [TERM](/docs/glossary/TERM)
+      const escapedRoute = routeBasePath.replace(
+        /[.*+?^${}()|[\]\\]/g,
+        '\\$&'
+      );
+
+      const termRegex = new RegExp(
+        `^${escapedRoute}[\\w-]+$`
+      );
+
+      if (termRegex.test(href)) {
+        const termSlug = href.replace(routeBasePath, '');
+        const termName = node.children.map((n) => n.value || '').join('');
+
+        // Replace with a valid MDX JSX element instead of raw HTML
+        const jsxNode = {
+          type: 'mdxJsxTextElement',
+          name: 'TermTooltip',
+          attributes: [
+            {
+              type: 'mdxJsxAttribute',
+              name: 'term',
+              value: termSlug,
+            },
+            {
+              type: 'mdxJsxAttribute',
+              name: 'href',
+              value: href,
+            },
+          ],
+          children: [
+            {
+              type: 'text',
+              value: termName,
+            },
+          ],
+        };
+
+        parent.children[index] = jsxNode;
+      }
+    });
+  };
+}
+module.exports = termLinkTransformer;

package/src/index.d.ts

@@ -0,0 +1,11 @@
+import { Plugin } from '@docusaurus/types';
+
+export interface TerminologyPluginOptions {
+  termsDir?: string;
+  routeBasePath?: string;
+  hideTermsFromSidebar?: boolean;
+}
+
+declare function pluginTerminology(context: any, options?: TerminologyPluginOptions): Plugin;
+
+export default pluginTerminology;

package/theme/Glossary.jsx

@@ -0,0 +1,74 @@
+// docusaurus-plugin-terminology/theme/Glossary.jsx
+import React from 'react';
+import { usePluginData } from '@docusaurus/useGlobalData';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+export default function Glossary() {
+  const { i18n } = useDocusaurusContext();
+  const pluginData = usePluginData('docusaurus-plugin-terminology');
+
+  const localeTerms =
+    pluginData.terms?.[i18n.currentLocale] || {};
+
+  const routeBasePath =
+    pluginData.routeBasePath || '/docs/terms/';
+  const termEntries = Object.entries(localeTerms);
+
+  if (termEntries.length === 0) {
+    return <p>No glossary terms found.</p>;
+  }
+
+  // Group terms by their starting letter
+  const groupedTerms = termEntries.reduce((acc, [key, { name, description }]) => {
+    const firstLetter = name[0].toUpperCase();
+    if (!acc[firstLetter]) {
+      acc[firstLetter] = [];
+    }
+    acc[firstLetter].push({ key, name, description });
+    return acc;
+  }, {});
+
+  const alphabet = Array.from({ length: 26 }, (_, i) => String.fromCharCode(65 + i));
+
+  // Filter out letters with no terms
+  const filteredAlphabet = alphabet.filter((letter) => groupedTerms[letter]);
+
+  return (
+    <div className="container">
+      {/* A-Z Index */}
+      <div className="container margin-bottom--lg">
+        {filteredAlphabet.map((letter) => (
+          <a
+            className="button button--sm button--outline button--primary col col--1 margin--xs"
+            key={letter}
+            href={`#${letter}`}
+          >
+            {letter}
+          </a>
+        ))}
+      </div>
+
+      {/* Terms List */}
+      <div>
+        {filteredAlphabet.map((letter) => (
+          <div key={letter} id={letter} className="container margin-vert--xs padding-vert--lg shadow--md">
+            <h2>{letter}</h2>
+            <ul>
+              {groupedTerms[letter].map(({ key, name, description }) => (
+                <li 
+                    key={key}
+                    style={{ listStyleType: 'none' }}
+                >
+                  <strong>
+                    <a href={`${routeBasePath}${key}`}>{name}</a>:
+                  </strong>{' '}
+                  {description}
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/theme/tooltip.js

@@ -0,0 +1,30 @@
+// docusaurus-plugin-terminology/theme/tooltip.js
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import tippy from 'tippy.js';
+import 'tippy.js/dist/tippy.css';
+//import 'tippy.js/themes/light-border.css';
+import 'tippy.js/themes/material.css';
+
+if (ExecutionEnvironment.canUseDOM) {
+  document.addEventListener('DOMContentLoaded', () => {
+    const locale = document.documentElement.lang || 'en';
+    const allTerms = window.Docusaurus?.__pluginGlobalData?.['docusaurus-plugin-terminology'] || {};
+    const terms = allTerms[locale] || {};
+
+    document.querySelectorAll('.term-tooltip').forEach((el) => {
+      const slug = el.dataset.term;
+      const info = terms[slug];
+      if (!info) return;
+
+      tippy(el, {
+        content: info.description,
+        allowHTML: true,
+        //theme: 'light-border',
+        theme: 'material',
+        placement: 'top-end',
+        delay: [100, 50],
+        maxWidth: 300,
+      });
+    });
+  });
+}