docusaurus-plugin-glossary 1.0.0

package/README.md

@@ -0,0 +1,320 @@
+# docusaurus-plugin-glossary
+
+A comprehensive Docusaurus plugin that provides glossary functionality with an auto-generated glossary page, searchable terms, and inline term tooltips.
+
+## Features
+
+- **Auto-generated Glossary Page**: Displays all terms alphabetically with letter navigation
+- **Search Functionality**: Real-time search across terms and definitions
+- **GlossaryTerm Component**: Inline component for linking terms with tooltip previews
+- **Responsive Design**: Mobile-friendly UI with dark mode support
+- **Related Terms**: Link between related glossary terms
+- **Abbreviation Support**: Display full form of abbreviated terms
+- **Customizable**: Configure glossary path and route
+
+## Installation
+
+### For Local Use (Same Repository)
+
+1. Copy the plugin directory to your Docusaurus site:
+
+   ```
+   src/plugins/docusaurus-plugin-glossary/
+   ```
+
+2. Add the plugin to your `docusaurus.config.js`:
+   ```javascript
+   plugins: [
+     [
+       require.resolve('./src/plugins/docusaurus-plugin-glossary'),
+       {
+         glossaryPath: 'glossary/glossary.json', // optional, default: 'glossary/glossary.json'
+         routePath: '/glossary', // optional, default: '/glossary'
+       },
+     ],
+   ];
+   ```
+
+### For Separate Package (To Publish)
+
+To publish this as a separate npm package:
+
+1. Create a new directory for the package:
+
+   ```bash
+   mkdir docusaurus-plugin-glossary
+   cd docusaurus-plugin-glossary
+   ```
+
+2. Copy the plugin files:
+
+   ```
+   docusaurus-plugin-glossary/
+   ├── index.js
+   ├── components/
+   │   ├── GlossaryPage.js
+   │   └── GlossaryPage.module.css
+   ├── theme/
+   │   └── GlossaryTerm/
+   │       ├── index.js
+   │       └── styles.module.css
+   ├── package.json
+   └── README.md
+   ```
+
+3. Create a `package.json`:
+
+   ```json
+   {
+     "name": "docusaurus-plugin-glossary",
+     "version": "1.0.0",
+     "description": "A Docusaurus plugin for creating and managing glossary terms",
+     "main": "index.js",
+     "keywords": ["docusaurus", "glossary", "plugin", "documentation"],
+     "peerDependencies": {
+       "@docusaurus/core": "^3.0.0",
+       "react": "^18.0.0",
+       "react-dom": "^18.0.0"
+     },
+     "dependencies": {
+       "fs-extra": "^11.0.0"
+     }
+   }
+   ```
+
+4. Publish to npm:
+
+   ```bash
+   npm publish
+   ```
+
+5. Install in your Docusaurus site:
+
+   ```bash
+   npm install docusaurus-plugin-glossary
+   ```
+
+6. Add to your `docusaurus.config.js`:
+   ```javascript
+   plugins: [
+     [
+       'docusaurus-plugin-glossary',
+       {
+         glossaryPath: 'glossary/glossary.json',
+         routePath: '/glossary',
+       },
+     ],
+   ];
+   ```
+
+## Usage
+
+### 1. Create a Glossary Data File
+
+Create a JSON file at `glossary/glossary.json` (or your configured path):
+
+```json
+{
+  "description": "A collection of technical terms and their definitions",
+  "terms": [
+    {
+      "term": "API",
+      "abbreviation": "Application Programming Interface",
+      "definition": "A set of rules and protocols that allows different software applications to communicate with each other.",
+      "relatedTerms": ["REST", "GraphQL"]
+    },
+    {
+      "term": "REST",
+      "abbreviation": "Representational State Transfer",
+      "definition": "An architectural style for designing networked applications.",
+      "relatedTerms": ["API", "HTTP"]
+    }
+  ]
+}
+```
+
+### 2. Glossary Data Structure
+
+Each term object can include:
+
+- `term` (required): The glossary term
+- `definition` (required): The term's definition
+- `abbreviation` (optional): The full form if the term is an abbreviation
+- `relatedTerms` (optional): Array of related term names
+- `id` (optional): Custom ID for linking (auto-generated from term if not provided)
+
+### 3. Using the GlossaryTerm Component
+
+Import and use the `GlossaryTerm` component in your MDX files:
+
+```jsx
+import GlossaryTerm from '@theme/GlossaryTerm';
+
+This website uses an <GlossaryTerm term="API" definition="Application Programming Interface">API</GlossaryTerm> to fetch data.
+
+// Or with default display (term name):
+We use <GlossaryTerm term="REST" definition="Representational State Transfer" /> for our web services.
+```
+
+The component features:
+
+- Dotted underline styling
+- Tooltip showing definition on hover
+- Link to full glossary page entry
+- Accessible with keyboard navigation
+
+### 4. Accessing the Glossary Page
+
+The glossary page is automatically available at `/glossary` (or your configured `routePath`).
+
+Features:
+
+- Alphabetical grouping with letter navigation
+- Real-time search
+- Related terms linking
+- Responsive design
+- Dark mode support
+
+## 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                            |
+
+## Customization
+
+### Styling
+
+The plugin uses CSS modules for styling. You can override styles by:
+
+1. Creating custom CSS in your site's `src/css/custom.css`:
+
+```css
+/* Override glossary term styles */
+.glossaryTermWrapper .glossaryTerm {
+  border-bottom-color: #your-color;
+}
+
+/* Override tooltip styles */
+.glossaryTermWrapper .tooltip {
+  background: #your-background;
+}
+```
+
+2. For advanced customization, you can swizzle the components:
+
+```bash
+npm run swizzle docusaurus-plugin-glossary GlossaryPage -- --wrap
+npm run swizzle docusaurus-plugin-glossary GlossaryTerm -- --wrap
+```
+
+### Adding to Navbar
+
+To add the glossary to your navbar, update your `docusaurus.config.js`:
+
+```javascript
+themeConfig: {
+  navbar: {
+    items: [
+      {to: '/glossary', label: 'Glossary', position: 'left'},
+      // ... other items
+    ],
+  },
+}
+```
+
+## Examples
+
+### Example 1: Technical Documentation
+
+```json
+{
+  "description": "Technical terms used in our documentation",
+  "terms": [
+    {
+      "term": "Webhook",
+      "definition": "An HTTP callback that occurs when something happens; a simple event-notification via HTTP POST.",
+      "relatedTerms": ["API", "HTTP"]
+    }
+  ]
+}
+```
+
+### Example 2: Using in MDX
+
+```mdx
+---
+title: API Documentation
+---
+
+import GlossaryTerm from '@theme/GlossaryTerm';
+
+# Getting Started with Our API
+
+Our <GlossaryTerm term="API" definition="Application Programming Interface" />
+uses <GlossaryTerm term="REST" definition="Representational State Transfer">RESTful</GlossaryTerm>
+principles to provide a simple and consistent interface.
+```
+
+## Development
+
+### File Structure
+
+```
+docusaurus-plugin-glossary/
+├── index.js                    # Main plugin file
+├── components/
+│   ├── GlossaryPage.js        # Glossary page component
+│   └── GlossaryPage.module.css # Glossary page styles
+├── theme/
+│   └── GlossaryTerm/
+│       ├── index.js           # Term component
+│       └── styles.module.css  # Term styles
+└── README.md
+```
+
+### Plugin Lifecycle
+
+1. **loadContent**: Reads glossary JSON file
+2. **contentLoaded**: Creates data file and adds route
+3. **getThemePath**: Exposes theme components
+4. **getPathsToWatch**: Watches glossary file for changes
+
+## Troubleshooting
+
+### Glossary page returns 404
+
+- Ensure the plugin is properly configured in `docusaurus.config.js`
+- Check that the `routePath` doesn't conflict with existing routes
+- Run `npm run clear` to clear Docusaurus cache
+
+### Glossary terms not showing
+
+- Verify `glossary/glossary.json` exists at the correct path
+- Check JSON syntax is valid
+- Ensure `terms` array is properly formatted
+
+### GlossaryTerm component not found
+
+- Make sure you're importing from `@theme/GlossaryTerm`
+- Try clearing cache with `npm run clear`
+- Restart dev server
+
+### Styles not applying
+
+- Check for CSS conflicts in your custom CSS
+- Ensure CSS modules are loading correctly
+- Try clearing cache and rebuilding
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Credits
+
+Built for Docusaurus v3.x

package/components/GlossaryPage.js

@@ -0,0 +1,138 @@
+import React, { useState, useMemo } from 'react';
+import Layout from '@theme/Layout';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import styles from './GlossaryPage.module.css';
+
+/**
+ * Groups glossary terms by their first letter
+ */
+function groupTermsByLetter(terms) {
+  const grouped = {};
+
+  terms.forEach(term => {
+    const firstLetter = term.term.charAt(0).toUpperCase();
+    if (!grouped[firstLetter]) {
+      grouped[firstLetter] = [];
+    }
+    grouped[firstLetter].push(term);
+  });
+
+  // Sort each group alphabetically
+  Object.keys(grouped).forEach(letter => {
+    grouped[letter].sort((a, b) => a.term.localeCompare(b.term));
+  });
+
+  return grouped;
+}
+
+/**
+ * GlossaryPage component - displays all glossary terms
+ */
+export default function GlossaryPage({ glossaryData }) {
+  const { siteConfig } = useDocusaurusContext();
+  const [searchTerm, setSearchTerm] = useState('');
+
+  const terms = glossaryData?.terms || [];
+
+  // Filter terms based on search
+  const filteredTerms = useMemo(() => {
+    if (!searchTerm) return terms;
+
+    const lowerSearch = searchTerm.toLowerCase();
+    return terms.filter(
+      term =>
+        term.term.toLowerCase().includes(lowerSearch) ||
+        term.definition.toLowerCase().includes(lowerSearch)
+    );
+  }, [terms, searchTerm]);
+
+  // Group terms by first letter
+  const groupedTerms = useMemo(() => {
+    return groupTermsByLetter(filteredTerms);
+  }, [filteredTerms]);
+
+  const letters = Object.keys(groupedTerms).sort();
+
+  return (
+    <Layout title="Glossary" description="A glossary of terms and definitions">
+      <div className={styles.glossaryContainer}>
+        <header className={styles.glossaryHeader}>
+          <h1>Glossary</h1>
+          <p className={styles.glossaryDescription}>
+            {glossaryData?.description || 'A collection of terms and their definitions'}
+          </p>
+
+          <div className={styles.searchContainer}>
+            <input
+              type="text"
+              placeholder="Search terms..."
+              className={styles.searchInput}
+              value={searchTerm}
+              onChange={e => setSearchTerm(e.target.value)}
+            />
+          </div>
+        </header>
+
+        {filteredTerms.length === 0 ? (
+          <div className={styles.noResults}>
+            <p>No terms found matching "{searchTerm}"</p>
+          </div>
+        ) : (
+          <div className={styles.glossaryContent}>
+            {/* Letter navigation */}
+            <nav className={styles.letterNav}>
+              {letters.map(letter => (
+                <a key={letter} href={`#letter-${letter}`} className={styles.letterLink}>
+                  {letter}
+                </a>
+              ))}
+            </nav>
+
+            {/* Terms grouped by letter */}
+            {letters.map(letter => (
+              <section key={letter} id={`letter-${letter}`} className={styles.letterSection}>
+                <h2 className={styles.letterHeading}>{letter}</h2>
+                <dl className={styles.termList}>
+                  {groupedTerms[letter].map((term, index) => (
+                    <div
+                      key={`${letter}-${index}`}
+                      className={styles.termItem}
+                      id={term.id || term.term.toLowerCase().replace(/\s+/g, '-')}
+                    >
+                      <dt className={styles.termName}>
+                        {term.term}
+                        {term.abbreviation && (
+                          <span className={styles.abbreviation}> ({term.abbreviation})</span>
+                        )}
+                      </dt>
+                      <dd className={styles.termDefinition}>
+                        {term.definition}
+                        {term.relatedTerms && term.relatedTerms.length > 0 && (
+                          <div className={styles.relatedTerms}>
+                            <strong>Related terms:</strong>{' '}
+                            {term.relatedTerms.map((related, idx) => (
+                              <React.Fragment key={idx}>
+                                {idx > 0 && ', '}
+                                <a href={`#${related.toLowerCase().replace(/\s+/g, '-')}`}>
+                                  {related}
+                                </a>
+                              </React.Fragment>
+                            ))}
+                          </div>
+                        )}
+                      </dd>
+                    </div>
+                  ))}
+                </dl>
+              </section>
+            ))}
+          </div>
+        )}
+
+        <footer className={styles.glossaryFooter}>
+          <p>Total terms: {terms.length}</p>
+        </footer>
+      </div>
+    </Layout>
+  );
+}

package/components/GlossaryPage.module.css

@@ -0,0 +1,189 @@
+.glossaryContainer {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 2rem 1rem;
+}
+
+.glossaryHeader {
+  text-align: center;
+  margin-bottom: 3rem;
+}
+
+.glossaryHeader h1 {
+  font-size: 2.5rem;
+  margin-bottom: 1rem;
+}
+
+.glossaryDescription {
+  font-size: 1.1rem;
+  color: var(--ifm-color-emphasis-700);
+  margin-bottom: 2rem;
+}
+
+.searchContainer {
+  max-width: 500px;
+  margin: 0 auto;
+}
+
+.searchInput {
+  width: 100%;
+  padding: 0.75rem 1rem;
+  font-size: 1rem;
+  border: 2px solid var(--ifm-color-emphasis-300);
+  border-radius: 0.5rem;
+  background: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+  transition: border-color 0.2s;
+}
+
+.searchInput:focus {
+  outline: none;
+  border-color: var(--ifm-color-primary);
+}
+
+.noResults {
+  text-align: center;
+  padding: 3rem 1rem;
+  color: var(--ifm-color-emphasis-600);
+}
+
+.glossaryContent {
+  margin-top: 2rem;
+}
+
+.letterNav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  justify-content: center;
+  margin-bottom: 2rem;
+  padding: 1rem;
+  background: var(--ifm-color-emphasis-100);
+  border-radius: 0.5rem;
+}
+
+.letterLink {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  font-weight: bold;
+  color: var(--ifm-color-primary);
+  text-decoration: none;
+  border-radius: 0.25rem;
+  transition: all 0.2s;
+}
+
+.letterLink:hover {
+  background: var(--ifm-color-primary);
+  color: white;
+}
+
+.letterSection {
+  margin-bottom: 3rem;
+}
+
+.letterHeading {
+  font-size: 2rem;
+  color: var(--ifm-color-primary);
+  border-bottom: 2px solid var(--ifm-color-emphasis-300);
+  padding-bottom: 0.5rem;
+  margin-bottom: 1.5rem;
+}
+
+.termList {
+  display: grid;
+  gap: 1.5rem;
+}
+
+.termItem {
+  padding: 1.5rem;
+  background: var(--ifm-card-background-color);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  border-radius: 0.5rem;
+  transition: all 0.2s;
+}
+
+.termItem:hover {
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.termName {
+  font-size: 1.25rem;
+  font-weight: bold;
+  color: var(--ifm-heading-color);
+  margin-bottom: 0.75rem;
+}
+
+.abbreviation {
+  font-size: 0.9rem;
+  color: var(--ifm-color-emphasis-600);
+  font-weight: normal;
+}
+
+.termDefinition {
+  margin: 0;
+  line-height: 1.6;
+  color: var(--ifm-color-emphasis-800);
+}
+
+.relatedTerms {
+  margin-top: 1rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--ifm-color-emphasis-200);
+  font-size: 0.9rem;
+  color: var(--ifm-color-emphasis-700);
+}
+
+.relatedTerms a {
+  color: var(--ifm-color-primary);
+  text-decoration: none;
+}
+
+.relatedTerms a:hover {
+  text-decoration: underline;
+}
+
+.glossaryFooter {
+  margin-top: 3rem;
+  padding-top: 2rem;
+  border-top: 1px solid var(--ifm-color-emphasis-200);
+  text-align: center;
+  color: var(--ifm-color-emphasis-600);
+}
+
+/* Dark mode adjustments */
+[data-theme='dark'] .termItem {
+  background: var(--ifm-background-surface-color);
+}
+
+[data-theme='dark'] .searchInput {
+  background: var(--ifm-background-surface-color);
+}
+
+/* Responsive design */
+@media (max-width: 768px) {
+  .glossaryHeader h1 {
+    font-size: 2rem;
+  }
+
+  .letterNav {
+    gap: 0.25rem;
+  }
+
+  .letterLink {
+    width: 1.75rem;
+    height: 1.75rem;
+    font-size: 0.9rem;
+  }
+
+  .termItem {
+    padding: 1rem;
+  }
+
+  .termName {
+    font-size: 1.1rem;
+  }
+}

package/components/GlossaryPage.test.js

@@ -0,0 +1,205 @@
+import React from 'react';
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import GlossaryPage from './GlossaryPage';
+
+// Mock CSS modules
+jest.mock('./GlossaryPage.module.css', () => ({
+  glossaryContainer: 'glossaryContainer',
+  glossaryHeader: 'glossaryHeader',
+  glossaryDescription: 'glossaryDescription',
+  searchContainer: 'searchContainer',
+  searchInput: 'searchInput',
+  noResults: 'noResults',
+  glossaryContent: 'glossaryContent',
+  letterNav: 'letterNav',
+  letterLink: 'letterLink',
+  letterSection: 'letterSection',
+  letterHeading: 'letterHeading',
+  termList: 'termList',
+  termItem: 'termItem',
+  termName: 'termName',
+  abbreviation: 'abbreviation',
+  termDefinition: 'termDefinition',
+  relatedTerms: 'relatedTerms',
+  glossaryFooter: 'glossaryFooter',
+}));
+
+const mockGlossaryData = {
+  description: 'Test glossary',
+  terms: [
+    {
+      id: 'api',
+      term: 'API',
+      definition: 'Application Programming Interface',
+      abbreviation: 'API',
+      relatedTerms: ['REST'],
+    },
+    {
+      id: 'rest',
+      term: 'REST',
+      definition: 'Representational State Transfer',
+      abbreviation: 'REST',
+      relatedTerms: ['API'],
+    },
+    {
+      id: 'ml',
+      term: 'Machine Learning',
+      definition: 'A type of artificial intelligence',
+    },
+  ],
+};
+
+describe('GlossaryPage', () => {
+  it('should render glossary with all terms', () => {
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    expect(screen.getByText('Glossary')).toBeInTheDocument();
+    expect(screen.getByText('Test glossary')).toBeInTheDocument();
+    // Use getAllBy since terms can appear multiple times (in term names and related links)
+    expect(screen.getAllByText('API').length).toBeGreaterThan(0);
+    expect(screen.getAllByText('REST').length).toBeGreaterThan(0);
+    expect(screen.getByText('Machine Learning')).toBeInTheDocument();
+  });
+
+  it('should show search input', () => {
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    const searchInput = screen.getByPlaceholderText('Search terms...');
+    expect(searchInput).toBeInTheDocument();
+  });
+
+  it('should filter terms by search query', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    const searchInput = screen.getByPlaceholderText('Search terms...');
+    await user.type(searchInput, 'API');
+
+    expect(screen.getByText('API')).toBeInTheDocument();
+    expect(screen.queryByText('Machine Learning')).not.toBeInTheDocument();
+  });
+
+  it('should filter by definition text', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    const searchInput = screen.getByPlaceholderText('Search terms...');
+    await user.type(searchInput, 'artificial');
+
+    expect(screen.getByText('Machine Learning')).toBeInTheDocument();
+    expect(screen.queryByText('API')).not.toBeInTheDocument();
+    expect(screen.queryByText('REST')).not.toBeInTheDocument();
+  });
+
+  it('should show no results message when no matches', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    const searchInput = screen.getByPlaceholderText('Search terms...');
+    await user.type(searchInput, 'NonexistentTerm');
+
+    expect(screen.getByText(/No terms found matching/)).toBeInTheDocument();
+  });
+
+  it('should group terms by first letter', () => {
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    // Check that terms are grouped under their first letter (multiple elements per letter)
+    expect(screen.getAllByText('A').length).toBeGreaterThan(0);
+    expect(screen.getAllByText('M').length).toBeGreaterThan(0);
+    expect(screen.getAllByText('R').length).toBeGreaterThan(0);
+  });
+
+  it('should sort terms alphabetically within groups', () => {
+    const dataWithMultipleTerms = {
+      ...mockGlossaryData,
+      terms: [
+        { id: 'zebra', term: 'Zebra', definition: 'An animal' },
+        { id: 'alpha', term: 'Alpha', definition: 'First letter' },
+        { id: 'beta', term: 'Beta', definition: 'Second letter' },
+      ],
+    };
+
+    render(<GlossaryPage glossaryData={dataWithMultipleTerms} />);
+
+    const terms = screen.getAllByText(/Zebra|Alpha|Beta/);
+    expect(terms).toHaveLength(3);
+    // Check Alpha is before Beta, and Beta is before Zebra
+    expect(terms[0]).toHaveTextContent('Alpha');
+    expect(terms[1]).toHaveTextContent('Beta');
+    expect(terms[2]).toHaveTextContent('Zebra');
+  });
+
+  it('should display abbreviations', () => {
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    // Check abbreviation appears in document
+    expect(screen.getAllByText('(API)').length).toBeGreaterThan(0);
+    expect(screen.getAllByText('(REST)').length).toBeGreaterThan(0);
+  });
+
+  it('should display related terms', () => {
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    // Related terms header appears multiple times (once per term with related terms)
+    expect(screen.getAllByText('Related terms:').length).toBeGreaterThan(0);
+    // REST appears as a term and in related links
+    expect(screen.getAllByText('REST').length).toBeGreaterThan(0);
+  });
+
+  it('should show total term count in footer', () => {
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    expect(screen.getByText('Total terms: 3')).toBeInTheDocument();
+  });
+
+  it('should handle empty terms array', () => {
+    const emptyData = { terms: [] };
+    render(<GlossaryPage glossaryData={emptyData} />);
+
+    expect(screen.getByText('Glossary')).toBeInTheDocument();
+    expect(screen.getByText('Total terms: 0')).toBeInTheDocument();
+  });
+
+  it('should handle missing glossaryData gracefully', () => {
+    render(<GlossaryPage glossaryData={null} />);
+
+    expect(screen.getByText('Glossary')).toBeInTheDocument();
+    expect(screen.getByText('Total terms: 0')).toBeInTheDocument();
+  });
+
+  it('should handle missing description gracefully', () => {
+    const dataWithoutDescription = {
+      terms: mockGlossaryData.terms,
+    };
+    render(<GlossaryPage glossaryData={dataWithoutDescription} />);
+
+    expect(screen.getByText(/A collection of terms and their definitions/)).toBeInTheDocument();
+  });
+
+  it('should generate correct anchor links for terms', () => {
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    // Check navigation links are generated
+    const navLinks = screen.getAllByRole('link', { name: /^[AMR]$/ });
+    expect(navLinks.length).toBeGreaterThan(0);
+    expect(navLinks[0]).toHaveAttribute('href', '#letter-A');
+  });
+
+  it('should clear search when input is cleared', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryPage glossaryData={mockGlossaryData} />);
+
+    const searchInput = screen.getByPlaceholderText('Search terms...');
+    await user.type(searchInput, 'Machine');
+
+    expect(screen.getByText('Machine Learning')).toBeInTheDocument();
+
+    await user.clear(searchInput);
+
+    expect(screen.getAllByText('API').length).toBeGreaterThan(0);
+    expect(screen.getAllByText('REST').length).toBeGreaterThan(0);
+    expect(screen.getByText('Machine Learning')).toBeInTheDocument();
+  });
+});

package/index.js

@@ -0,0 +1,70 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+/**
+ * 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
+ *
+ * @param {object} context - Docusaurus context
+ * @param {object} options - Plugin options
+ * @param {string} options.glossaryPath - Path to glossary JSON file (default: 'glossary/glossary.json')
+ * @param {string} options.routePath - Route path for glossary page (default: '/glossary')
+ * @returns {object} Plugin object
+ */
+function glossaryPlugin(context, options = {}) {
+  const { glossaryPath = 'glossary/glossary.json', routePath = '/glossary' } = options;
+
+  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);
+        return glossaryData;
+      }
+
+      console.warn(`Glossary file not found at ${glossaryFilePath}. Using empty glossary.`);
+      return { terms: [] };
+    },
+
+    async contentLoaded({ content, actions }) {
+      const { createData, addRoute } = actions;
+
+      // Create data file that can be imported by components
+      const glossaryDataPath = await createData('glossary-data.json', JSON.stringify(content));
+
+      // Add glossary page route
+      addRoute({
+        path: routePath,
+        component: '@site/src/plugins/docusaurus-plugin-glossary/components/GlossaryPage.js',
+        exact: true,
+        modules: {
+          glossaryData: glossaryDataPath,
+        },
+      });
+    },
+
+    getThemePath() {
+      return path.resolve(__dirname, './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');
+    },
+  };
+}
+
+module.exports = glossaryPlugin;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "docusaurus-plugin-glossary",
+  "version": "1.0.0",
+  "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "components/",
+    "theme/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm test",
+    "version": "npm version",
+    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\"",
+    "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,css,md}\""
+  },
+  "keywords": [
+    "docusaurus",
+    "glossary",
+    "plugin",
+    "documentation",
+    "terms",
+    "definitions",
+    "tooltip"
+  ],
+  "author": "mcclowes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcclowes/docusaurus-plugin-glossary.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mcclowes/docusaurus-plugin-glossary/issues"
+  },
+  "homepage": "https://github.com/mcclowes/docusaurus-plugin-glossary#readme",
+  "peerDependencies": {
+    "@docusaurus/core": "^3.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "dependencies": {
+    "fs-extra": "^11.0.0"
+  },
+  "engines": {
+    "node": ">=16.14"
+  },
+  "devDependencies": {
+    "@babel/preset-env": "^7.28.5",
+    "@babel/preset-react": "^7.28.5",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "babel-jest": "^30.2.0",
+    "identity-obj-proxy": "^3.0.0",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "prettier": "^3.6.2"
+  }
+}

package/theme/GlossaryTerm/index.js

@@ -0,0 +1,49 @@
+import React, { useState } from 'react';
+import styles from './styles.module.css';
+
+/**
+ * GlossaryTerm component - displays an inline term with tooltip
+ *
+ * Usage:
+ * import GlossaryTerm from '@theme/GlossaryTerm';
+ *
+ * <GlossaryTerm term="API" definition="Application Programming Interface" />
+ * or
+ * <GlossaryTerm term="API">custom display text</GlossaryTerm>
+ *
+ * @param {object} props
+ * @param {string} props.term - The glossary term
+ * @param {string} props.definition - The definition to show in tooltip
+ * @param {React.ReactNode} props.children - Optional custom display text
+ */
+export default function GlossaryTerm({ term, definition, children }) {
+  const [showTooltip, setShowTooltip] = useState(false);
+
+  const displayText = children || term;
+  const termId = term.toLowerCase().replace(/\s+/g, '-');
+
+  return (
+    <span className={styles.glossaryTermWrapper}>
+      <a
+        href={`/glossary#${termId}`}
+        className={styles.glossaryTerm}
+        onMouseEnter={() => setShowTooltip(true)}
+        onMouseLeave={() => setShowTooltip(false)}
+        onFocus={() => setShowTooltip(true)}
+        onBlur={() => setShowTooltip(false)}
+        aria-describedby={`tooltip-${termId}`}
+      >
+        {displayText}
+      </a>
+      {definition && (
+        <span
+          id={`tooltip-${termId}`}
+          className={`${styles.tooltip} ${showTooltip ? styles.tooltipVisible : ''}`}
+          role="tooltip"
+        >
+          <strong>{term}:</strong> {definition}
+        </span>
+      )}
+    </span>
+  );
+}

package/theme/GlossaryTerm/index.test.js

@@ -0,0 +1,116 @@
+import React from 'react';
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import GlossaryTerm from './index';
+
+describe('GlossaryTerm', () => {
+  it('should render term text', () => {
+    render(<GlossaryTerm term="API" definition="Application Programming Interface" />);
+
+    const link = screen.getByRole('link', { name: 'API' });
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveAttribute('href', '/glossary#api');
+  });
+
+  it('should render custom children text', () => {
+    render(
+      <GlossaryTerm term="API" definition="Application Programming Interface">
+        Application Programming Interface
+      </GlossaryTerm>
+    );
+
+    const link = screen.getByRole('link', { name: 'Application Programming Interface' });
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveAttribute('href', '/glossary#api');
+  });
+
+  it('should show tooltip on hover', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryTerm term="API" definition="Application Programming Interface" />);
+
+    const link = screen.getByRole('link');
+    await user.hover(link);
+
+    const tooltip = screen.getByRole('tooltip');
+    expect(tooltip).toBeInTheDocument();
+    expect(tooltip).toHaveClass('tooltipVisible');
+    expect(tooltip).toHaveTextContent('API: Application Programming Interface');
+  });
+
+  it('should hide tooltip on mouse leave', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryTerm term="API" definition="Application Programming Interface" />);
+
+    const link = screen.getByRole('link');
+    await user.hover(link);
+
+    let tooltip = screen.getByRole('tooltip');
+    expect(tooltip).toBeInTheDocument();
+    expect(tooltip).toHaveClass('tooltipVisible');
+
+    await user.unhover(link);
+    // Tooltip is still in DOM but hidden via CSS
+    tooltip = screen.getByRole('tooltip');
+    expect(tooltip).not.toHaveClass('tooltipVisible');
+  });
+
+  it('should show tooltip on focus', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryTerm term="API" definition="Application Programming Interface" />);
+
+    const link = screen.getByRole('link');
+    await user.tab();
+    expect(link).toHaveFocus();
+
+    const tooltip = screen.getByRole('tooltip');
+    expect(tooltip).toBeInTheDocument();
+    expect(tooltip).toHaveClass('tooltipVisible');
+  });
+
+  it('should hide tooltip on blur', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryTerm term="API" definition="Application Programming Interface" />);
+
+    const link = screen.getByRole('link');
+    await user.tab();
+    expect(link).toHaveFocus();
+
+    let tooltip = screen.getByRole('tooltip');
+    expect(tooltip).toBeInTheDocument();
+    expect(tooltip).toHaveClass('tooltipVisible');
+
+    await user.tab();
+    // Tooltip is still in DOM but hidden via CSS
+    tooltip = screen.getByRole('tooltip');
+    expect(tooltip).not.toHaveClass('tooltipVisible');
+  });
+
+  it('should generate correct ID from term with spaces', () => {
+    render(<GlossaryTerm term="Machine Learning" definition="A type of AI" />);
+
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('href', '/glossary#machine-learning');
+  });
+
+  it('should work without definition prop', () => {
+    render(<GlossaryTerm term="TestTerm" />);
+
+    const link = screen.getByRole('link', { name: 'TestTerm' });
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveAttribute('href', '/glossary#testterm');
+
+    // No tooltip should be rendered when no definition
+    const tooltip = screen.queryByRole('tooltip');
+    expect(tooltip).not.toBeInTheDocument();
+  });
+
+  it('should have proper ARIA attributes', () => {
+    render(<GlossaryTerm term="API" definition="Application Programming Interface" />);
+
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('aria-describedby', 'tooltip-api');
+
+    const tooltip = screen.getByRole('tooltip');
+    expect(tooltip).toHaveAttribute('id', 'tooltip-api');
+  });
+});

package/theme/GlossaryTerm/styles.module.css

@@ -0,0 +1,95 @@
+.glossaryTermWrapper {
+  position: relative;
+  display: inline;
+}
+
+.glossaryTerm {
+  color: var(--ifm-color-primary);
+  text-decoration: none;
+  border-bottom: 1px dotted var(--ifm-color-primary);
+  cursor: help;
+  font-weight: 500;
+  transition: all 0.2s;
+}
+
+.glossaryTerm:hover {
+  color: var(--ifm-color-primary-dark);
+  border-bottom-style: solid;
+}
+
+.tooltip {
+  position: absolute;
+  bottom: 100%;
+  left: 50%;
+  transform: translateX(-50%) translateY(-8px);
+  padding: 0.75rem 1rem;
+  background: var(--ifm-background-surface-color);
+  color: var(--ifm-font-color-base);
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 0.5rem;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+  font-size: 0.875rem;
+  line-height: 1.4;
+  white-space: normal;
+  max-width: 300px;
+  min-width: 200px;
+  z-index: 1000;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.2s;
+}
+
+.tooltip::after {
+  content: '';
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  border: 6px solid transparent;
+  border-top-color: var(--ifm-background-surface-color);
+}
+
+.tooltip::before {
+  content: '';
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  border: 7px solid transparent;
+  border-top-color: var(--ifm-color-emphasis-300);
+  margin-top: 1px;
+}
+
+.tooltipVisible {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.tooltip strong {
+  display: block;
+  margin-bottom: 0.25rem;
+  color: var(--ifm-color-primary);
+}
+
+/* Dark mode adjustments */
+[data-theme='dark'] .tooltip {
+  background: var(--ifm-background-surface-color);
+  border-color: var(--ifm-color-emphasis-400);
+}
+
+[data-theme='dark'] .tooltip::after {
+  border-top-color: var(--ifm-background-surface-color);
+}
+
+[data-theme='dark'] .tooltip::before {
+  border-top-color: var(--ifm-color-emphasis-400);
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+  .tooltip {
+    max-width: 250px;
+    min-width: 180px;
+    font-size: 0.8rem;
+  }
+}