docusaurus-plugin-glossary 1.1.0 → 1.2.0

package/README.md

@@ -18,11 +18,13 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
 ## Quick Start
 
 1. **Install the plugin:**
+
    ```bash
    npm install docusaurus-plugin-glossary
    ```
 
 2. **Add to your `docusaurus.config.js`:**
+
    ```javascript
    module.exports = {
      // ... other config
@@ -39,10 +41,11 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
      // ... other config
    };
    ```
-   
+
    **That’s it!** On Docusaurus v3, the remark plugin is automatically configured via the plugin’s `configureMarkdown` hook — no manual `markdown.remarkPlugins` setup needed.
 
 3. **Create your glossary file at `glossary/glossary.json`:**
+
    ```json
    {
      "description": "A collection of technical terms and their definitions",
@@ -64,11 +67,12 @@ A comprehensive Docusaurus plugin that provides glossary functionality with an a
    ```
 
 4. **Start your dev server:**
+
    ```bash
    npm run start
    ```
 
-5. **That's it!** 
+5. **That's it!**
    - Visit `/glossary` to see your glossary page
    - Write markdown normally - terms will automatically be linked with tooltips
    - Use `<GlossaryTerm>` component in MDX for manual control
@@ -108,10 +112,12 @@ Create a JSON file at `glossary/glossary.json` (or your configured path) in your
 ```
 
 **Required fields:**
+
 - `term` (string): The glossary term name
 - `definition` (string): The term's definition
 
 **Optional fields:**
+
 - `abbreviation` (string): The full form if the term is an abbreviation
 - `relatedTerms` (string[]): Array of related term names that link to other glossary entries
 - `id` (string): Custom ID for linking (auto-generated from term name if not provided)
@@ -173,10 +179,10 @@ module.exports = {
 ## Docusaurus v3 Notes and Troubleshooting
 
 - **MDX imports**: The plugin injects `import GlossaryTerm from '@theme/GlossaryTerm';` automatically when it auto-links a term. If you’re writing MDX manually, you can also import and use it yourself:
-  
+
   ```mdx
   import GlossaryTerm from '@theme/GlossaryTerm';
-  
+
   Our <GlossaryTerm term="API" /> uses <GlossaryTerm term="REST">RESTful</GlossaryTerm> principles.
   ```
 
@@ -201,12 +207,14 @@ This project supports webhooks for real-time notifications.
 ```
 
 Terms like "API", "REST", and "webhooks" will automatically be:
+
 - Detected if they're defined in your glossary
 - Styled with a dotted underline
 - Display a tooltip with the definition on hover
 - Link to the full glossary page entry
 
 **Limitations:**
+
 - Only whole words are matched (respects word boundaries)
 - Terms inside code blocks, links, or existing MDX components are **not** processed
 - Matching is case-insensitive
@@ -228,6 +236,7 @@ Our <GlossaryTerm term="API" definition="Application Programming Interface">REST
 ```
 
 **Component props:**
+
 - `term` (required): The term name (used to look up definition from glossary)
 - `definition` (optional): Override the definition from the glossary file
 - `children` (optional): Custom text to display (defaults to term name)
@@ -237,6 +246,7 @@ Our <GlossaryTerm term="API" definition="Application Programming Interface">REST
 The glossary page is automatically available at `/glossary` (or your configured `routePath`).
 
 **Features:**
+
 - Alphabetical grouping with letter navigation
 - Real-time search across terms and definitions
 - Clickable related terms
@@ -252,7 +262,7 @@ module.exports = {
   themeConfig: {
     navbar: {
       items: [
-        {to: '/glossary', label: 'Glossary', position: 'left'},
+        { to: '/glossary', label: 'Glossary', position: 'left' },
         // ... other items
       ],
     },
@@ -262,11 +272,11 @@ module.exports = {
 
 ## 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                            |
-| `autoLinkTerms`| boolean | `true`                     | Enable automatic term detection in markdown (requires remark plugin configuration) |
+| 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                                                         |
+| `autoLinkTerms` | boolean | `true`                     | Enable automatic term detection in markdown (requires remark plugin configuration) |
 
 ## Customization
 
@@ -449,7 +459,7 @@ MIT
 
 ## Contributing
 
-Contributions are welcome! Please open an issue or submit a pull request.
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started.
 
 ## Credits
 

package/index.js

@@ -19,10 +19,10 @@ const fs = require('fs-extra');
  * @returns {object} Plugin object
  */
 function glossaryPlugin(context, options = {}) {
-  const { 
-    glossaryPath = 'glossary/glossary.json', 
+  const {
+    glossaryPath = 'glossary/glossary.json',
     routePath = '/glossary',
-    autoLinkTerms = true
+    autoLinkTerms = true,
   } = options;
 
   let glossaryDataCache = { terms: [] };
@@ -40,16 +40,14 @@ function glossaryPlugin(context, options = {}) {
         const remarkPlugin = require('./remark/glossary-terms');
 
         // Check if the remark plugin is already configured
-        const isAlreadyConfigured = markdownConfig.remarkPlugins.some(
-          (plugin) => {
-            if (Array.isArray(plugin) && plugin[0]) {
-              // Check if it's our remark plugin by comparing the function reference
-              return plugin[0] === remarkPlugin;
-            }
-            // Also check if it's directly the remark plugin function
-            return plugin === remarkPlugin;
+        const isAlreadyConfigured = markdownConfig.remarkPlugins.some(plugin => {
+          if (Array.isArray(plugin) && plugin[0]) {
+            // Check if it's our remark plugin by comparing the function reference
+            return plugin[0] === remarkPlugin;
           }
-        );
+          // Also check if it's directly the remark plugin function
+          return plugin === remarkPlugin;
+        });
 
         // Only add if not already configured
         if (!isAlreadyConfigured) {
@@ -59,7 +57,7 @@ function glossaryPlugin(context, options = {}) {
               glossaryPath,
               routePath,
               siteDir: context.siteDir,
-            }
+            },
           ]);
         }
       }
@@ -81,11 +79,11 @@ function glossaryPlugin(context, options = {}) {
     },
 
     async contentLoaded({ content, actions }) {
-      const { createData, addRoute } = actions;
+      const { createData, addRoute, setGlobalData } = actions;
 
       // Create data file that can be imported by components
       const glossaryDataPath = await createData('glossary-data.json', JSON.stringify(content));
-      
+
       // Create a data file for the remark plugin to access glossary terms
       const remarkGlossaryDataPath = await createData(
         'remark-glossary-data.json',
@@ -104,6 +102,12 @@ function glossaryPlugin(context, options = {}) {
           glossaryData: glossaryDataPath,
         },
       });
+
+      // Expose global data for runtime lookups (used by GlossaryTerm)
+      setGlobalData({
+        terms: content.terms || [],
+        routePath,
+      });
     },
 
     getThemePath() {
@@ -127,16 +131,16 @@ glossaryPlugin.remarkPlugin = require('./remark/glossary-terms');
 /**
  * Helper function to get the configured remark plugin
  * This can be used in docusaurus.config.js markdown configuration
- * 
+ *
  * @param {object} pluginOptions - Plugin options from docusaurus.config.js
  * @param {object} context - Docusaurus context
  * @returns {function} Configured remark plugin
  */
-glossaryPlugin.getRemarkPlugin = function(pluginOptions, context) {
-  const { 
-    glossaryPath = 'glossary/glossary.json', 
+glossaryPlugin.getRemarkPlugin = function (pluginOptions, context) {
+  const {
+    glossaryPath = 'glossary/glossary.json',
     routePath = '/glossary',
-    siteDir = context.siteDir
+    siteDir = context.siteDir,
   } = pluginOptions;
 
   return [
@@ -145,7 +149,7 @@ glossaryPlugin.getRemarkPlugin = function(pluginOptions, context) {
       glossaryPath,
       routePath,
       siteDir,
-    }
+    },
   ];
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-glossary",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A Docusaurus plugin for creating and managing glossary terms with auto-generated pages and inline tooltips",
   "main": "index.js",
   "files": [
@@ -15,6 +15,9 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "example:start": "npm --prefix examples/docusaurus-v3 run start",
+    "example:build": "npm --prefix examples/docusaurus-v3 run build",
+    "example:serve": "npm --prefix examples/docusaurus-v3 run serve",
     "prepublishOnly": "npm test",
     "version": "npm version",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\"",

package/remark/glossary-terms.js

@@ -1,10 +1,12 @@
-const visit = require('unist-util-visit');
+// Support both CJS and ESM exports of unist-util-visit
+let visit = require('unist-util-visit');
+visit = visit && visit.visit ? visit.visit : visit;
 const path = require('path');
 const fs = require('fs');
 
 /**
  * Creates a remark plugin that automatically detects and replaces glossary terms in markdown
- * 
+ *
  * @param {object} options - Plugin options
  * @param {Array} options.terms - Array of glossary term objects with {term, definition}
  * @param {string} options.glossaryPath - Path to glossary JSON file (optional, if terms not provided)
@@ -12,11 +14,11 @@ const fs = require('fs');
  * @param {string} options.siteDir - Docusaurus site directory (required if using glossaryPath)
  * @returns {function} Remark plugin function
  */
-function remarkGlossaryTerms({ 
-  terms = [], 
+function remarkGlossaryTerms({
+  terms = [],
   glossaryPath = null,
   routePath = '/glossary',
-  siteDir = null
+  siteDir = null,
 } = {}) {
   let glossaryTerms = terms;
 
@@ -44,13 +46,11 @@ function remarkGlossaryTerms({
 
   // Sort terms by length (longest first) to avoid partial matches
   // e.g., "Application Programming Interface" should match before "API"
-  const sortedTerms = Array.from(termMap.entries()).sort(
-    (a, b) => b[0].length - a[0].length
-  );
+  const sortedTerms = Array.from(termMap.entries()).sort((a, b) => b[0].length - a[0].length);
 
   // If no terms, return a no-op transformer
   if (sortedTerms.length === 0) {
-    return (tree) => tree;
+    return tree => tree;
   }
 
   /**
@@ -71,29 +71,47 @@ function remarkGlossaryTerms({
     for (const [lowerTerm, termObj] of sortedTerms) {
       const term = termObj.term;
       let searchIndex = 0;
-      
+
       while (searchIndex < textLower.length) {
         const index = textLower.indexOf(lowerTerm, searchIndex);
         if (index === -1) break;
 
-        // Check if it's a whole word match
+        // Check if it's a whole word match, with simple plural tolerance ('s' or 'es')
         const beforeChar = index > 0 ? textLower[index - 1] : ' ';
-        const afterChar = index + lowerTerm.length < textLower.length 
-          ? textLower[index + lowerTerm.length] 
+        const afterIndex = index + lowerTerm.length;
+        const afterChar = afterIndex < textLower.length 
+          ? textLower[afterIndex] 
           : ' ';
         
-        // Word boundary check (alphanumeric characters)
-        const isWordBoundary = 
-          !/\w/.test(beforeChar) && !/\w/.test(afterChar);
+        let matchLength = term.length;
+        let isWordBoundary = !/\w/.test(beforeChar) && !/\w/.test(afterChar);
+
+        // Allow trailing 's' plural (e.g., webhook -> webhooks)
+        if (!isWordBoundary && afterChar === 's') {
+          const nextChar = afterIndex + 1 < textLower.length ? textLower[afterIndex + 1] : ' ';
+          if (!/\w/.test(nextChar)) {
+            isWordBoundary = true;
+            matchLength = term.length + 1;
+          }
+        }
+
+        // Allow trailing 'es' plural (e.g., API -> APIs, box -> boxes)
+        if (!isWordBoundary && afterChar === 'e' && afterIndex + 1 < textLower.length && textLower[afterIndex + 1] === 's') {
+          const nextChar = afterIndex + 2 < textLower.length ? textLower[afterIndex + 2] : ' ';
+          if (!/\w/.test(nextChar)) {
+            isWordBoundary = true;
+            matchLength = term.length + 2;
+          }
+        }
 
         if (isWordBoundary) {
           matches.push({
             index,
-            length: term.length,
+            length: matchLength,
             term: term,
             termObj: termObj,
             // Store original case from the text
-            originalText: text.substring(index, index + term.length)
+            originalText: text.substring(index, index + matchLength)
           });
         }
 
@@ -120,7 +138,7 @@ function remarkGlossaryTerms({
       if (match.index > lastIndex) {
         result.push({
           type: 'text',
-          value: text.substring(lastIndex, match.index)
+          value: text.substring(lastIndex, match.index),
         });
       }
 
@@ -132,25 +150,25 @@ function remarkGlossaryTerms({
           {
             type: 'mdxJsxAttribute',
             name: 'term',
-            value: match.termObj.term
+            value: match.termObj.term,
           },
           {
             type: 'mdxJsxAttribute',
             name: 'definition',
-            value: match.termObj.definition || ''
+            value: match.termObj.definition || '',
           },
           {
             type: 'mdxJsxAttribute',
             name: 'routePath',
-            value: routePath
-          }
+            value: routePath,
+          },
         ],
         children: [
           {
             type: 'text',
-            value: match.originalText
-          }
-        ]
+            value: match.originalText,
+          },
+        ],
       });
 
       lastIndex = match.index + match.length;
@@ -160,14 +178,14 @@ function remarkGlossaryTerms({
     if (lastIndex < text.length) {
       result.push({
         type: 'text',
-        value: text.substring(lastIndex)
+        value: text.substring(lastIndex),
       });
     }
 
     return result.length > 0 ? result : [{ type: 'text', value: text }];
   }
 
-  return (tree) => {
+  return tree => {
     let usedGlossaryTerm = false;
     visit(tree, 'text', (node, index, parent) => {
       // Skip text nodes inside code blocks, links, or existing MDX components
@@ -185,8 +203,10 @@ function remarkGlossaryTerms({
       const replacements = replaceTermsInText(node.value);
 
       // If we have replacements, replace the single text node with multiple nodes
-      if (replacements.length > 1 || 
-          (replacements.length === 1 && replacements[0].type !== 'text')) {
+      if (
+        replacements.length > 1 ||
+        (replacements.length === 1 && replacements[0].type !== 'text')
+      ) {
         // Convert to text elements for paragraph context if needed
         const newNodes = replacements.map(replacement => {
           if (replacement.type === 'mdxJsxFlowElement') {
@@ -196,7 +216,7 @@ function remarkGlossaryTerms({
                 type: 'mdxJsxTextElement',
                 name: replacement.name,
                 attributes: replacement.attributes,
-                children: replacement.children
+                children: replacement.children,
               };
             }
           }
@@ -217,9 +237,10 @@ function remarkGlossaryTerms({
 
     // Inject MDX import for GlossaryTerm if we used it anywhere in this file
     if (usedGlossaryTerm) {
+      // Create import node matching MDX expectations (empty value + estree)
       const importNode = {
         type: 'mdxjsEsm',
-        value: "import GlossaryTerm from '@theme/GlossaryTerm';",
+        value: '',
         data: {
           estree: {
             type: 'Program',
@@ -230,26 +251,51 @@ function remarkGlossaryTerms({
                 specifiers: [
                   {
                     type: 'ImportDefaultSpecifier',
-                    local: { type: 'Identifier', name: 'GlossaryTerm' }
-                  }
+                    local: { type: 'Identifier', name: 'GlossaryTerm' },
+                  },
                 ],
-                source: { type: 'Literal', value: '@theme/GlossaryTerm' }
-              }
-            ]
-          }
-        }
+                source: { type: 'Literal', value: '@theme/GlossaryTerm' },
+              },
+            ],
+          },
+        },
       };
 
       // Avoid duplicate imports if already present
-      const hasExistingImport = Array.isArray(tree.children) && tree.children.some(
-        (n) => n.type === 'mdxjsEsm' && typeof n.value === 'string' && n.value.includes("@theme/GlossaryTerm")
-      );
+      const hasExistingImport =
+        Array.isArray(tree.children) &&
+        tree.children.some(n => {
+          if (n.type !== 'mdxjsEsm') return false;
+          // Check value string (for older MDX format)
+          if (typeof n.value === 'string' && n.value.includes('@theme/GlossaryTerm')) {
+            return true;
+          }
+          // Check estree data (for newer MDX format)
+          if (n.data?.estree?.body) {
+            return n.data.estree.body.some(
+              stmt =>
+                stmt.type === 'ImportDeclaration' &&
+                stmt.source?.value === '@theme/GlossaryTerm'
+            );
+          }
+          return false;
+        });
+      
       if (!hasExistingImport) {
+        // Place import at the very beginning of the file (before all other nodes)
+        // This ensures it's available when MDX compiles the JSX elements
+        if (!Array.isArray(tree.children)) {
+          tree.children = [];
+        }
+        // Insert at the very beginning (index 0) to ensure it's processed first
         tree.children.unshift(importNode);
+        // Debug: verify import was added (remove in production)
+        if (process.env.NODE_ENV !== 'production') {
+          console.log('[glossary-plugin] Injected GlossaryTerm import');
+        }
       }
     }
   };
 }
 
 module.exports = remarkGlossaryTerms;
-

package/theme/GlossaryTerm/index.js

@@ -1,4 +1,5 @@
-import React, { useState } from 'react';
+import React, { useMemo, useState, useRef, useEffect, useCallback } from 'react';
+import { usePluginData } from '@docusaurus/useGlobalData';
 import styles from './styles.module.css';
 
 /**
@@ -19,14 +20,83 @@ import styles from './styles.module.css';
  */
 export default function GlossaryTerm({ term, definition, routePath = '/glossary', children }) {
   const [showTooltip, setShowTooltip] = useState(false);
+  const [tooltipStyle, setTooltipStyle] = useState(null);
+  const [placement, setPlacement] = useState('top'); // 'top' | 'bottom'
+  const wrapperRef = useRef(null);
+  const tooltipRef = useRef(null);
+
+  const updatePosition = useCallback(() => {
+    if (!wrapperRef.current || !tooltipRef.current) return;
+    const wrapperRect = wrapperRef.current.getBoundingClientRect();
+    const tooltipRect = tooltipRef.current.getBoundingClientRect();
+
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    const preferredGap = 8; // px
+
+    // Decide top vs bottom based on available space
+    const hasSpaceAbove = wrapperRect.top >= tooltipRect.height + preferredGap;
+    const hasSpaceBelow = viewportHeight - wrapperRect.bottom >= tooltipRect.height + preferredGap;
+    const nextPlacement = hasSpaceAbove || !hasSpaceBelow ? 'top' : 'bottom';
+
+    let top;
+    if (nextPlacement === 'top') {
+      top = wrapperRect.top - tooltipRect.height - preferredGap;
+    } else {
+      top = wrapperRect.bottom + preferredGap;
+    }
+
+    // Center horizontally on the wrapper, then clamp within viewport with margin
+    const horizontalMargin = 8;
+    let left = wrapperRect.left + wrapperRect.width / 2 - tooltipRect.width / 2;
+    left = Math.max(
+      horizontalMargin,
+      Math.min(left, viewportWidth - tooltipRect.width - horizontalMargin)
+    );
+
+    setPlacement(nextPlacement);
+    setTooltipStyle({ top: Math.max(4, top), left });
+  }, []);
+
+  useEffect(() => {
+    if (!showTooltip) return;
+    updatePosition();
+    const onScroll = () => updatePosition();
+    const onResize = () => updatePosition();
+    window.addEventListener('scroll', onScroll, true);
+    window.addEventListener('resize', onResize);
+    return () => {
+      window.removeEventListener('scroll', onScroll, true);
+      window.removeEventListener('resize', onResize);
+    };
+  }, [showTooltip, updatePosition]);
+
+  // Pull definition/route from plugin global data if not provided
+  const pluginData = usePluginData('docusaurus-plugin-glossary');
+  const effectiveDefinition = useMemo(() => {
+    if (definition && typeof definition === 'string' && definition.length > 0) {
+      return definition;
+    }
+    const terms = (pluginData && pluginData.terms) || [];
+    const found = terms.find(
+      t => typeof t.term === 'string' && t.term.toLowerCase() === String(term).toLowerCase()
+    );
+    return found && found.definition ? found.definition : undefined;
+  }, [definition, pluginData, term]);
+
+  const effectiveRoutePath = useMemo(() => {
+    if (routePath && typeof routePath === 'string' && routePath.length > 0) return routePath;
+    return (pluginData && pluginData.routePath) || '/glossary';
+  }, [pluginData, routePath]);
 
   const displayText = children || term;
   const termId = term.toLowerCase().replace(/\s+/g, '-');
 
   return (
-    <span className={styles.glossaryTermWrapper}>
+    <span ref={wrapperRef} className={styles.glossaryTermWrapper}>
       <a
-        href={`${routePath}#${termId}`}
+        href={`${effectiveRoutePath}#${termId}`}
         className={styles.glossaryTerm}
         onMouseEnter={() => setShowTooltip(true)}
         onMouseLeave={() => setShowTooltip(false)}
@@ -36,13 +106,23 @@ export default function GlossaryTerm({ term, definition, routePath = '/glossary'
       >
         {displayText}
       </a>
-      {definition && (
+      {effectiveDefinition && (
         <span
+          ref={tooltipRef}
           id={`tooltip-${termId}`}
-          className={`${styles.tooltip} ${showTooltip ? styles.tooltipVisible : ''}`}
+          className={
+            `${styles.tooltip} ${showTooltip ? styles.tooltipVisible : ''} ` +
+            `${placement === 'top' ? styles.tooltipTop : styles.tooltipBottom} ` +
+            `${styles.tooltipFloating}`
+          }
           role="tooltip"
+          style={
+            showTooltip && tooltipStyle
+              ? { top: `${tooltipStyle.top}px`, left: `${tooltipStyle.left}px` }
+              : undefined
+          }
         >
-          <strong>{term}:</strong> {definition}
+          <strong>{term}:</strong> {effectiveDefinition}
         </span>
       )}
     </span>

package/theme/GlossaryTerm/index.test.js

@@ -113,4 +113,23 @@ describe('GlossaryTerm', () => {
     const tooltip = screen.getByRole('tooltip');
     expect(tooltip).toHaveAttribute('id', 'tooltip-api');
   });
+
+  it('positions tooltip within viewport and adds placement classes', async () => {
+    const user = userEvent.setup();
+    render(<GlossaryTerm term="Edge" definition="Near the boundary of the viewport" />);
+
+    const link = screen.getByRole('link');
+    await user.hover(link);
+
+    const tooltip = screen.getByRole('tooltip');
+    expect(tooltip).toHaveClass('tooltipVisible');
+    expect(tooltip).toHaveClass('tooltipFloating');
+    // One of the placement classes should be present
+    const hasPlacement =
+      tooltip.classList.contains('tooltipTop') || tooltip.classList.contains('tooltipBottom');
+    expect(hasPlacement).toBe(true);
+    // Inline style should include computed top/left
+    expect(tooltip.style.top).toMatch(/px$/);
+    expect(tooltip.style.left).toMatch(/px$/);
+  });
 });

package/theme/GlossaryTerm/styles.module.css

@@ -40,25 +40,55 @@
   visibility: hidden;
 }
 
-.tooltip::after {
+/* When we compute viewport-safe placement via JS */
+.tooltipFloating {
+  position: fixed;
+  bottom: auto;
+  transform: none;
+  left: 0; /* overridden inline */
+  top: 0; /* overridden inline */
+}
+
+/* Base arrow removed; arrows are defined per-placement to avoid inversion */
+
+/* Arrow for top placement (tooltip above anchor) */
+.tooltipTop::after {
   content: '';
   position: absolute;
-  top: 100%;
   left: 50%;
   transform: translateX(-50%);
+  bottom: -6px;
   border: 6px solid transparent;
-  border-top-color: var(--ifm-background-surface-color);
+  border-bottom-color: var(--ifm-background-surface-color);
+}
+.tooltipTop::before {
+  content: '';
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  bottom: -7px;
+  border: 7px solid transparent;
+  border-bottom-color: var(--ifm-color-emphasis-300);
 }
 
-.tooltip::before {
+/* Arrow for bottom placement (tooltip below anchor) */
+.tooltipBottom::after {
   content: '';
   position: absolute;
-  top: 100%;
   left: 50%;
   transform: translateX(-50%);
+  top: -6px;
+  border: 6px solid transparent;
+  border-top-color: var(--ifm-background-surface-color);
+}
+.tooltipBottom::before {
+  content: '';
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  top: -7px;
   border: 7px solid transparent;
   border-top-color: var(--ifm-color-emphasis-300);
-  margin-top: 1px;
 }
 
 .tooltipVisible {
@@ -79,11 +109,17 @@
   border-color: var(--ifm-color-emphasis-400);
 }
 
-[data-theme='dark'] .tooltip::after {
+/* Dark mode arrow overrides scoped to placement to avoid upside-down arrows */
+[data-theme='dark'] .tooltipTop::after {
+  border-bottom-color: var(--ifm-background-surface-color);
+}
+[data-theme='dark'] .tooltipTop::before {
+  border-bottom-color: var(--ifm-color-emphasis-400);
+}
+[data-theme='dark'] .tooltipBottom::after {
   border-top-color: var(--ifm-background-surface-color);
 }
-
-[data-theme='dark'] .tooltip::before {
+[data-theme='dark'] .tooltipBottom::before {
   border-top-color: var(--ifm-color-emphasis-400);
 }