docusaurus-plugin-terminology 0.1.0 → 0.2.0

package/theme/Glossary.jsx

@@ -1,74 +1,80 @@
-// docusaurus-plugin-terminology/theme/Glossary.jsx
 import React from 'react';
-import { usePluginData } from '@docusaurus/useGlobalData';
+import Link from '@docusaurus/Link';
+import {usePluginData} from '@docusaurus/useGlobalData';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import styles from './styles.module.css';
+import {normalizeRouteBasePath} from './terminology';
 
+/**
+ * A–Z glossary listing every term with its short description.
+ *
+ * Usage in any Markdown/MDX file:
+ *
+ * ```mdx
+ * import Glossary from '@theme/Glossary';
+ *
+ * <Glossary />
+ * ```
+ */
 export default function Glossary() {
-  const { i18n } = useDocusaurusContext();
+  const {i18n} = useDocusaurusContext();
   const pluginData = usePluginData('docusaurus-plugin-terminology');
 
   const localeTerms =
-    pluginData.terms?.[i18n.currentLocale] || {};
+    pluginData?.terms?.[i18n.currentLocale] ??
+    pluginData?.terms?.[i18n.defaultLocale] ??
+    {};
 
-  const routeBasePath =
-    pluginData.routeBasePath || '/docs/terms/';
-  const termEntries = Object.entries(localeTerms);
+  const routeBasePath = normalizeRouteBasePath(
+    pluginData?.routeBasePath ?? '/terms/',
+  );
+
+  const termEntries = Object.entries(localeTerms).sort(([, a], [, b]) =>
+    a.name.localeCompare(b.name),
+  );
 
   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 });
+  const groupedTerms = termEntries.reduce((acc, [slug, term]) => {
+    const firstLetter = (term.name[0] || '#').toUpperCase();
+    (acc[firstLetter] ||= []).push({slug, ...term});
     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]);
+  const alphabet = Object.keys(groupedTerms).sort();
 
   return (
-    <div className="container">
-      {/* A-Z Index */}
-      <div className="container margin-bottom--lg">
-        {filteredAlphabet.map((letter) => (
+    <div>
+      <nav className={styles.alphabetNav} aria-label="Glossary index">
+        {alphabet.map((letter) => (
           <a
-            className="button button--sm button--outline button--primary col col--1 margin--xs"
             key={letter}
-            href={`#${letter}`}
-          >
+            className="button button--sm button--outline button--primary"
+            href={`#${letter}`}>
             {letter}
           </a>
         ))}
-      </div>
+      </nav>
 
-      {/* 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' }}
-                >
+      {alphabet.map((letter) => (
+        <section key={letter} id={letter} className={styles.glossarySection}>
+          <h2>{letter}</h2>
+          <dl className={styles.glossaryList}>
+            {groupedTerms[letter].map(({slug, name, description}) => (
+              <div key={slug} className={styles.glossaryEntry}>
+                <dt>
                   <strong>
-                    <a href={`${routeBasePath}${key}`}>{name}</a>:
-                  </strong>{' '}
-                  {description}
-                </li>
-              ))}
-            </ul>
-          </div>
-        ))}
-      </div>
+                    <Link to={`${routeBasePath}${slug}`}>{name}</Link>
+                  </strong>
+                </dt>
+                <dd>{description}</dd>
+              </div>
+            ))}
+          </dl>
+        </section>
+      ))}
     </div>
   );
 }

package/theme/MDXComponents/A.jsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import OriginalA from '@theme-init/MDXComponents/A';
+import {usePluginData} from '@docusaurus/useGlobalData';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import TermTooltip from '@theme/TermTooltip';
+import {getTermSlug} from '@theme/terminology';
+
+/**
+ * Override of the MDX `a` component.
+ *
+ * Plain Markdown links to term pages (e.g. `[AI](/terms/ai)`) are rendered as
+ * `<TermTooltip>`; every other link is delegated to the original Docusaurus
+ * implementation.
+ *
+ * This is what makes the plugin zero-config: no remark plugin, no MDX
+ * components swizzle, and no client-side DOM scanning. The term link is part of
+ * the server-rendered HTML, and the tooltip is attached on mount.
+ *
+ * @param {object} props
+ * @returns {React.ReactNode}
+ */
+export default function A(props) {
+  const pluginData = usePluginData('docusaurus-plugin-terminology');
+  const {siteConfig, i18n} = useDocusaurusContext();
+
+  if (pluginData) {
+    const slug = getTermSlug(props.href, {
+      routeBasePath: pluginData.routeBasePath,
+      baseUrl: siteConfig.baseUrl,
+      locales: i18n.locales,
+      defaultLocale: i18n.defaultLocale,
+      currentLocale: i18n.currentLocale,
+    });
+
+    const hasEntry =
+      slug &&
+      (pluginData.terms?.[i18n.currentLocale]?.[slug] ||
+        pluginData.terms?.[i18n.defaultLocale]?.[slug]);
+
+    if (hasEntry) {
+      return <TermTooltip slug={slug} {...props} />;
+    }
+  }
+
+  return <OriginalA {...props} />;
+}

package/theme/TermTooltip.jsx

@@ -0,0 +1,79 @@
+import React, {useEffect, useRef} from 'react';
+import Link from '@docusaurus/Link';
+import {usePluginData} from '@docusaurus/useGlobalData';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import tippy from 'tippy.js';
+import 'tippy.js/dist/tippy.css';
+import './tooltip.css';
+import styles from './styles.module.css';
+
+/**
+ * Resolve the glossary entry for a slug, falling back to the default locale.
+ */
+function resolveEntry(terms, locale, defaultLocale, slug) {
+  if (!slug) {
+    return undefined;
+  }
+  return terms?.[locale]?.[slug] ?? terms?.[defaultLocale]?.[slug];
+}
+
+/**
+ * A term link that renders a tippy.js tooltip with the term definition.
+ *
+ * SSR-safe: the `<a>` is part of the server-rendered markup (good for SEO and
+ * no-JS), while the tooltip itself is attached on mount — as tooltips are
+ * inherently an interactive, client-only enhancement.
+ */
+export default function TermTooltip({slug, href, children, className, ...rest}) {
+  const {i18n} = useDocusaurusContext();
+  const pluginData = usePluginData('docusaurus-plugin-terminology');
+
+  const entry = resolveEntry(
+    pluginData?.terms,
+    i18n.currentLocale,
+    i18n.defaultLocale,
+    slug,
+  );
+  const content = entry?.description;
+
+  // Attach to a wrapper element rather than the anchor: `@docusaurus/Link` only
+  // forwards refs on React 19, and this must also work on React 18.
+  const wrapperRef = useRef(null);
+
+  useEffect(() => {
+    const target = wrapperRef.current;
+    if (!target || !content) {
+      return undefined;
+    }
+
+    const instance = tippy(target, {
+      content,
+      allowHTML: false,
+      delay: [120, 0],
+      duration: [150, 120],
+      placement: 'top',
+      maxWidth: 360,
+      theme: 'terminology',
+      // Anchoring to an inline element needs inline positioning.
+      inlinePositioning: true,
+      // Keep the link usable (and the tooltip visible) while hovering it.
+      interactive: false,
+      appendTo: () => document.body,
+    });
+
+    return () => {
+      instance.destroy();
+    };
+  }, [content]);
+
+  return (
+    <span ref={wrapperRef} className={styles.termWrapper}>
+      <Link
+        {...rest}
+        to={href}
+        className={[styles.termLink, className].filter(Boolean).join(' ')}>
+        {children}
+      </Link>
+    </span>
+  );
+}

package/theme/styles.module.css

@@ -0,0 +1,38 @@
+.termWrapper {
+  white-space: normal;
+}
+
+.termLink {
+  text-decoration: underline;
+  text-decoration-style: dotted;
+  text-underline-offset: 0.2em;
+  cursor: help;
+}
+
+.alphabetNav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+  margin-bottom: 1.5rem;
+}
+
+.glossarySection {
+  margin-bottom: 1.5rem;
+  scroll-margin-top: 4rem;
+}
+
+.glossaryList {
+  margin: 0;
+}
+
+.glossaryEntry {
+  margin-bottom: 0.75rem;
+}
+
+.glossaryEntry dt {
+  font-weight: 600;
+}
+
+.glossaryEntry dd {
+  margin: 0.15rem 0 0;
+}

package/theme/terminology.jsx

@@ -0,0 +1,99 @@
+/**
+ * docusaurus-plugin-terminology/theme/terminology.js
+ *
+ * Client-side helpers shared by the theme components.
+ */
+
+/**
+ * Canonicalize a route base path to the form `/<segment>/`.
+ *
+ * @param {string} [routeBasePath]
+ * @returns {string}
+ */
+export function normalizeRouteBasePath(routeBasePath = '/terms/') {
+  let route = String(routeBasePath || '').trim();
+  if (route === '') {
+    return '/';
+  }
+  if (!route.startsWith('/')) {
+    route = `/${route}`;
+  }
+  if (!route.endsWith('/')) {
+    route = `${route}/`;
+  }
+  return route;
+}
+
+/**
+ * Extract the term slug from a link href, or `null` when it is not a term link.
+ *
+ * Handles absolute/relative URLs, the site `baseUrl`, and locale prefixes.
+ *
+ * @param {string|undefined} href
+ * @param {{
+ *   routeBasePath?: string,
+ *   baseUrl?: string,
+ *   locales?: string[],
+ *   defaultLocale?: string,
+ *   currentLocale?: string,
+ * }} [options]
+ * @returns {string|null}
+ */
+export function getTermSlug(href, options = {}) {
+  if (!href || typeof href !== 'string') {
+    return null;
+  }
+
+  let pathname = href;
+
+  // Strip a protocol/origin if present.
+  if (/^[a-z][a-z\d+.-]*:\/\//i.test(pathname)) {
+    try {
+      pathname = new URL(pathname).pathname;
+    } catch {
+      return null;
+    }
+  }
+
+  // Drop query string and hash.
+  pathname = pathname.split('#')[0].split('?')[0];
+  if (!pathname) {
+    return null;
+  }
+
+  const {baseUrl, routeBasePath, locales = [], defaultLocale} = options;
+
+  // Strip the site baseUrl (e.g. `/my-site/`).
+  if (baseUrl && baseUrl !== '/') {
+    const normalizedBase = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+    if (pathname === baseUrl.replace(/\/$/, '')) {
+      pathname = '/';
+    } else if (pathname.startsWith(normalizedBase)) {
+      pathname = `/${pathname.slice(normalizedBase.length)}`;
+    }
+  }
+
+  // Strip a locale prefix (e.g. `/de/terms/ai` -> `/terms/ai`).
+  const nonDefaultLocales = locales.filter(
+    (locale) => locale && locale !== defaultLocale,
+  );
+  for (const locale of nonDefaultLocales) {
+    if (pathname === `/${locale}`) {
+      pathname = '/';
+      break;
+    }
+    if (pathname.startsWith(`/${locale}/`)) {
+      pathname = pathname.slice(locale.length + 1);
+      break;
+    }
+  }
+
+  const base = normalizeRouteBasePath(routeBasePath);
+  if (!pathname.startsWith(base)) {
+    return null;
+  }
+
+  const rest = pathname.slice(base.length);
+  const slug = rest.split('/')[0];
+  return slug || null;
+}

package/theme/tooltip.css

@@ -0,0 +1,36 @@
+/**
+ * Tooltip styling for term links.
+ * Applied on top of `tippy.js/dist/tippy.css`.
+ */
+
+.tippy-box[data-theme~='terminology'] {
+  background-color: var(--ifm-background-surface-color, #fff);
+  color: var(--ifm-font-color-base, #1c1e21);
+  border: 1px solid var(--ifm-color-emphasis-300, rgba(0, 0, 0, 0.1));
+  border-radius: var(--ifm-global-radius, 0.4rem);
+  box-shadow: 0 4px 14px rgba(0, 0, 0, 0.15);
+  font-size: 0.85rem;
+  line-height: 1.45;
+  text-align: left;
+  padding: 0.4rem 0.6rem;
+}
+
+.tippy-box[data-theme~='terminology'] .tippy-content {
+  padding: 0;
+}
+
+.tippy-box[data-theme~='terminology'][data-placement^='top'] > .tippy-arrow::before {
+  border-top-color: var(--ifm-color-emphasis-300, rgba(0, 0, 0, 0.1));
+}
+
+.tippy-box[data-theme~='terminology'][data-placement^='bottom'] > .tippy-arrow::before {
+  border-bottom-color: var(--ifm-color-emphasis-300, rgba(0, 0, 0, 0.1));
+}
+
+.tippy-box[data-theme~='terminology'][data-placement^='left'] > .tippy-arrow::before {
+  border-left-color: var(--ifm-color-emphasis-300, rgba(0, 0, 0, 0.1));
+}
+
+.tippy-box[data-theme~='terminology'][data-placement^='right'] > .tippy-arrow::before {
+  border-right-color: var(--ifm-color-emphasis-300, rgba(0, 0, 0, 0.1));
+}

package/theme-plugin.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * docusaurus-plugin-terminology/theme-plugin.js
+ *
+ * A tiny theme-only plugin whose sole job is to expose the package's `theme/`
+ * directory to Docusaurus.
+ *
+ * It is registered by the preset under `themes`, i.e. with a higher priority
+ * than `@docusaurus/theme-classic`. This is what allows the package to override
+ * the MDX `a` component (SSR-safe link tooltips) without requiring users to
+ * swizzle or register anything themselves.
+ */
+
+const path = require('path');
+
+module.exports = function terminologyTheme() {
+  return {
+    name: 'docusaurus-plugin-terminology-theme',
+    getThemePath() {
+      return path.resolve(__dirname, 'theme');
+    },
+  };
+};

package/remark/term-link-transformer.js

@@ -1,64 +0,0 @@
-/**
- * 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/theme/tooltip.js

@@ -1,30 +0,0 @@
-// 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,
-      });
-    });
-  });
-}