Glossary Transformer, finds words wrapped in ^^...^^ and transforms to a GlossaryToolTip at build time.

Author: dhtclk

docs/concepts/why-clickhouse-is-so-fast.mdx

@@ -19,7 +19,7 @@ From an architectural perspective, databases consist (at least) of a storage lay
 
 <iframe width="1024" height="576" src="https://www.youtube.com/embed/vsykFYns0Ws?si=hE2qnOf6cDKn-otP" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-In ClickHouse, each table consists of multiple "table <GlossaryTooltip term="Parts" />". A [part](/parts) is created whenever a user inserts data into the table (INSERT statement). A query is always executed against all table parts that exist at the time the query starts.
+In ClickHouse, each table consists of multiple "table ^^parts^^". A [part](/parts) is created whenever a user inserts data into the table (INSERT statement). A query is always executed against all table parts that exist at the time the query starts.
 
 To avoid that too many parts accumulate, ClickHouse runs a [merge](/merges) operation in the background which continuously combines multiple smaller parts into a single bigger part.
 
@@ -97,7 +97,7 @@ Finally, ClickHouse uses a vectorized query processing layer that parallelizes q
 
 Modern systems have dozens of CPU cores. To utilize all cores, ClickHouse unfolds the query plan into multiple lanes, typically one per core. Each lane processes a disjoint range of the table data. That way, the performance of the database scales "vertically" with the number of available cores.
 
-If a single node becomes too small to hold the table data, further nodes can be added to form a <GlossaryTooltip term="Cluster" />. Tables can be split ("sharded") and distributed across the nodes. ClickHouse will run queries on all nodes that store table data and thereby scale "horizontally" with the number of available nodes.
+If a single node becomes too small to hold the table data, further nodes can be added to form a ^^cluster^^. Tables can be split ("sharded") and distributed across the nodes. ClickHouse will run queries on all nodes that store table data and thereby scale "horizontally" with the number of available nodes.
 
 🤿 Deep dive into this in the [Query Processing Layer](/academic_overview#4-query-processing-layer) section of the web version of our VLDB 2024 paper.
 

docs/getting-started/quick-start/cloud.mdx

@@ -60,7 +60,7 @@ Select your desired region for deploying the service, and give your new service
 <Image img={createservice1} size="md" alt='New ClickHouse Service' border/>
 <br/>
 
-By default, the scale tier will create 3 <GlossaryTooltip term="Replica" plural="s" /> each with 4 VCPUs and 16 GiB RAM. [Vertical autoscaling](/manage/scaling#vertical-auto-scaling) will be enabled by default in the Scale tier.
+By default, the scale tier will create 3 ^^replica^^s each with 4 VCPUs and 16 GiB RAM. [Vertical autoscaling](/manage/scaling#vertical-auto-scaling) will be enabled by default in the Scale tier.
 
 Users can customize the service resources if required, specifying a minimum and maximum size for replicas to scale between. When ready, select `Create service`.
 

docs/getting-started/quick-start/oss.mdx

@@ -1,7 +1,7 @@
 ---
 slug: /getting-started/quick-start/oss
 sidebar_label: 'OSS'
-sidebar_position: 1
+sidebar_position: 2
 keywords: ['getting started', 'quick start', 'beginner-friendly']
 title: 'ClickHouse OSS quick start'
 description: 'ClickHouse Quick Start guide'
@@ -107,7 +107,7 @@ PRIMARY KEY (user_id, timestamp)
 
 You can use the familiar `INSERT INTO TABLE` command with ClickHouse, but it is
 important to understand that each insert into a `MergeTree` table causes what we
-call a **part** in ClickHouse to be created in storage. These <GlossaryTooltip term="Parts" /> later get
+call a **part** in ClickHouse to be created in storage. These ^^parts^^ later get
 merged in the background by ClickHouse.
 
 In ClickHouse, we try to bulk insert lots of rows at a time

docusaurus.config.en.js

@@ -13,6 +13,7 @@ const frontmatterValidator = require('./plugins/frontmatter-validation/frontmatt
 import pluginLlmsTxt from './plugins/llms-txt-plugin.ts'
 import prismLight from "./src/utils/prismLight";
 import prismDark from "./src/utils/prismDark";
+import glossaryTransformer from "./plugins/glossary-transformer.js";
 
 // Helper function to skip over index.md files.
 function skipIndex(items) {
@@ -151,7 +152,7 @@ const config = {
           showLastUpdateTime: false,
           sidebarCollapsed: true,
           routeBasePath: "/",
-          remarkPlugins: [math, remarkCustomBlocks],
+          remarkPlugins: [math, remarkCustomBlocks, glossaryTransformer],
           beforeDefaultRemarkPlugins: [fixLinks],
           rehypePlugins: [katex],
         },

plugins/glossary-transformer.js

@@ -0,0 +1,140 @@
+// plugins/glossary-transformer/index.js
+const { visit } = require('unist-util-visit');
+const fs = require('fs');
+const path = require('path');
+
+// Cache glossary terms globally
+let cachedGlossary = null;
+let glossaryModTime = null;
+
+function createGlossaryTransformer(options = {}) {
+  const config = {
+    caseSensitive: false,
+    validateTerms: true,
+    glossaryFile: path.resolve(__dirname, '../src/components/GlossaryTooltip/glossary.json'),
+    skipPatterns: [],
+    ...options
+  };
+  
+  if (!Array.isArray(config.skipPatterns)) {
+    config.skipPatterns = [];
+  }
+  
+  function loadGlossary() {
+    if (!fs.existsSync(config.glossaryFile)) {
+      console.warn(`Glossary file not found: ${config.glossaryFile}`);
+      return new Map();
+    }
+    
+    const stats = fs.statSync(config.glossaryFile);
+    if (cachedGlossary && glossaryModTime && stats.mtime <= glossaryModTime) {
+      return cachedGlossary;
+    }
+    
+    try {
+      const glossaryData = JSON.parse(fs.readFileSync(config.glossaryFile, 'utf8'));
+      const glossaryMap = new Map();
+      
+      Object.entries(glossaryData).forEach(([term, definition]) => {
+        glossaryMap.set(term.toLowerCase(), { originalTerm: term, definition });
+      });
+      
+      cachedGlossary = glossaryMap;
+      glossaryModTime = stats.mtime;
+      console.log(`Loaded ${glossaryMap.size} glossary terms`);
+      
+      return glossaryMap;
+    } catch (error) {
+      console.error('Error loading glossary:', error.message);
+      return new Map();
+    }
+  }
+  
+  function shouldProcess(filePath, fileContent) {
+    return filePath?.endsWith('.mdx') && 
+           fileContent?.includes('^^') &&
+           !config.skipPatterns.some(pattern => 
+             pattern instanceof RegExp ? pattern.test(filePath) : filePath.includes(pattern)
+           );
+  }
+  
+  return function transformer(tree, file) {
+    const filePath = file.path || file.history?.[0] || '';
+    const fileContent = file.value || '';
+    
+    if (!shouldProcess(filePath, fileContent)) {
+      return tree;
+    }
+    
+    const glossary = loadGlossary();
+    if (glossary.size === 0) return tree;
+    
+    let transformCount = 0;
+    
+    visit(tree, 'text', (node, index, parent) => {
+      if (!node.value?.includes('^^') || !parent) return;
+      
+      const pattern = /\^\^([^^\n|]+?)(?:\|([^^\n]*?))?\^\^/g;
+      const newNodes = [];
+      let lastIndex = 0;
+      let match;
+      
+      while ((match = pattern.exec(node.value)) !== null) {
+        const [fullMatch, term, plural = ''] = match;
+        const cleanTerm = term.trim();
+        const cleanPlural = plural.trim();
+        
+        // Add text before match
+        if (match.index > lastIndex) {
+          newNodes.push({
+            type: 'text',
+            value: node.value.slice(lastIndex, match.index)
+          });
+        }
+        
+        // Get original term from glossary or use as-is
+        const glossaryEntry = glossary.get(cleanTerm.toLowerCase());
+        const originalTerm = glossaryEntry?.originalTerm || cleanTerm;
+        
+        if (!glossaryEntry && config.validateTerms) {
+          console.warn(`Glossary term not found: ${cleanTerm}`);
+        }
+        
+        // Create MDX JSX element
+        newNodes.push({
+          type: 'mdxJsxTextElement',
+          name: 'GlossaryTooltip',
+          attributes: [
+            { type: 'mdxJsxAttribute', name: 'term', value: originalTerm },
+            { type: 'mdxJsxAttribute', name: 'plural', value: cleanPlural }
+          ],
+          children: []
+        });
+        
+        transformCount++;
+        lastIndex = match.index + fullMatch.length;
+      }
+      
+      // Add remaining text
+      if (lastIndex < node.value.length) {
+        newNodes.push({
+          type: 'text',
+          value: node.value.slice(lastIndex)
+        });
+      }
+      
+      // Replace node if we made changes
+      if (newNodes.length > 0) {
+        parent.children.splice(index, 1, ...newNodes);
+      }
+    });
+    
+    if (transformCount > 0) {
+      console.log(`Processed ${transformCount} glossary terms in: ${path.basename(filePath)}`);
+    }
+    
+    return tree;
+  };
+}
+
+module.exports = createGlossaryTransformer;

scripts/inject-glossary-tooltips.py

@@ -4,7 +4,21 @@ import Link from '@docusaurus/Link';
 
 const GlossaryTooltip = ({ term, capitalize = false, plural = '' }) => {
   const [visible, setVisible] = useState(false);
-  const definition = glossary[term];
+  
+  // Case-insensitive lookup
+  let definition = glossary[term]; // Try exact match first
+  let matchedKey = term;
+  
+  if (!definition) {
+    // Try to find a case-insensitive match
+    const foundKey = Object.keys(glossary).find(key => 
+      key.toLowerCase() === term.toLowerCase()
+    );
+    if (foundKey) {
+      definition = glossary[foundKey];
+      matchedKey = foundKey;
+    }
+  }
 
   if (!definition) {
     console.warn(`Glossary term not found: ${term}`);
@@ -15,7 +29,7 @@ const GlossaryTooltip = ({ term, capitalize = false, plural = '' }) => {
   }
 
   const displayTerm = capitalize ? capitalizeWord(term) : term.toLowerCase();
-  const anchorId = term.toLowerCase().replace(/\s+/g, '-');
+  const anchorId = matchedKey.toLowerCase().replace(/\s+/g, '-');
   const glossarySlug = `/concepts/glossary#${anchorId}`;
 
   return (
@@ -46,4 +60,4 @@ function capitalizeWord(word) {
   return word.charAt(0).toUpperCase() + word.slice(1);
 }
 
-export default GlossaryTooltip;
+export default GlossaryTooltip;

src/components/GlossaryTooltip/GlossaryTooltip.tsx

@@ -5,7 +5,7 @@ import MDXComponents from '@theme-original/MDXComponents';
 // Import the custom Stepper component
 // Make sure the path matches your project structure
 import VStepper from '@site/src/components/Stepper/Stepper';
-import GlossaryTooltip from '../../src/components/GlossaryTooltip/GlossaryTooltip.tsx';
+import GlossaryTooltip from '@site/src/components/GlossaryTooltip/GlossaryTooltip';
 
 // Define the enhanced components
 const enhancedComponents = {