astro-mermaid 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # astro-mermaid
 
-An Astro integration for rendering Mermaid diagrams with automatic theme switching and client-side rendering. Instead of using playright, I used the approach done in https://github.com/cloudflare/cloudflare-docs
+An Astro integration for rendering Mermaid diagrams with automatic theme switching and client-side rendering. This follows the mermaid integration in [cloudflare-docs](https://github.com/cloudflare/cloudflare-docs)
 
 ## Features
 
@@ -10,6 +10,11 @@ An Astro integration for rendering Mermaid diagrams with automatic theme switchi
 - ⚡ Vite optimization for fast development
 - 🔧 Customizable mermaid configuration
 - 🎯 TypeScript support
+- 🔒 Privacy-focused with no external server dependencies
+- 🌐 Offline-capable rendering
+- ⚡ Zero network latency for diagram generation
+- 📦 Conditional loading - mermaid.js only loads on pages with diagrams
+- 🎭 Smooth loading animations to prevent layout shifts
 
 ## Installation
 
@@ -27,7 +32,28 @@ import mermaid from 'astro-mermaid';
 
 export default defineConfig({
   integrations: [
-    mermaid()
+    mermaid({
+      theme: 'forest'
+    })
+  ]
+});
+```
+
+### Important: Integration Order
+
+When using with Starlight or other integrations that process markdown, make sure to place the mermaid integration **before** them:
+
+```js
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import mermaid from 'astro-mermaid';
+
+export default defineConfig({
+  integrations: [
+    mermaid(), // Must come BEFORE starlight
+    starlight({
+      title: 'My Docs'
+    })
   ]
 });
 ```
@@ -59,10 +85,53 @@ mermaid({
     flowchart: {
       curve: 'basis'
     }
-  }
+  },
+  
+  // Register icon packs for use in diagrams
+  iconPacks: [
+    {
+      name: 'logos',
+      loader: () => fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then(res => res.json())
+    },
+    {
+      name: 'iconoir',
+      loader: () => fetch('https://unpkg.com/@iconify-json/iconoir@1/icons.json').then(res => res.json())
+    }
+  ]
 })
 ```
 
+## Icon Packs
+
+You can register icon packs to use custom icons in your diagrams. Icon packs are loaded from Iconify JSON sources:
+
+```js
+iconPacks: [
+  {
+    name: 'logos',
+    loader: () => fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then(res => res.json())
+  }
+]
+```
+
+Then use icons in your diagrams:
+
+````markdown
+```mermaid
+architecture-beta
+  group api(logos:aws-lambda)[API]
+
+  service db(logos:postgresql)[Database] in api
+  service disk1(logos:aws-s3)[Storage] in api
+  service disk2(logos:cloudflare)[CDN] in api
+  service server(logos:docker)[Server] in api
+
+  db:L -- R:server
+  disk1:T -- B:server
+  disk2:T -- B:db
+```
+````
+
 ## Theme Switching
 
 If `autoTheme` is enabled (default), the integration will automatically switch between themes based on your site's `data-theme` attribute:
@@ -70,6 +139,39 @@ If `autoTheme` is enabled (default), the integration will automatically switch b
 - `data-theme="light"` → uses 'default' mermaid theme
 - `data-theme="dark"` → uses 'dark' mermaid theme
 
+## Client-Side Rendering & Security
+
+### 🔒 Privacy & Security Benefits
+
+This integration uses **100% client-side rendering** with zero external dependencies at runtime:
+
+- **No Data Transmission**: Your diagram content never leaves your browser
+- **No External Servers**: No calls to mermaid.live or any external services
+- **Offline Capable**: Works completely offline after initial page load
+- **Zero Network Latency**: Instant diagram rendering without network delays
+- **Corporate Firewall Friendly**: No external domains need to be whitelisted
+
+### ⚡ How It Works
+
+1. **Build Time**: Mermaid code blocks are transformed to `<pre class="mermaid">` elements
+2. **Runtime**: The bundled Mermaid JavaScript library renders diagrams locally
+3. **Output**: Pure SVG generated entirely in your browser
+
+```javascript
+// All rendering happens locally - no network calls
+import mermaid from 'mermaid';
+const { svg } = await mermaid.render(id, diagramDefinition);
+```
+
+### 🛡️ Enterprise & Compliance
+
+Perfect for:
+- Corporate environments with strict security policies
+- GDPR/privacy-compliant applications  
+- Air-gapped or restricted network environments
+- Applications requiring data sovereignty
+- High-security environments where external requests are prohibited
+
 ## Supported Diagrams
 
 All mermaid diagram types are supported:
@@ -90,6 +192,14 @@ All mermaid diagram types are supported:
 - Quadrant charts
 - And more!
 
+## Demo
+
+Check out the [live demo](https://starlight-mermaid-demo.netlify.app/) built with Starlight.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
 ## License
 
 MIT

package/astro-mermaid-integration.d.ts

@@ -1,5 +1,17 @@
 import type { AstroIntegration } from 'astro';
 
+export interface IconPack {
+  /**
+   * Name of the icon pack
+   */
+  name: string;
+  
+  /**
+   * Function that returns a promise resolving to the icon pack data
+   */
+  loader: () => Promise<any>;
+}
+
 export interface AstroMermaidOptions {
   /**
    * Default mermaid theme
@@ -18,6 +30,20 @@ export interface AstroMermaidOptions {
    * @see https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults
    */
   mermaidConfig?: Record<string, any>;
+  
+  /**
+   * Icon packs to register with mermaid
+   * @example
+   * ```js
+   * iconPacks: [
+   *   {
+   *     name: 'logos',
+   *     loader: () => fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then(res => res.json())
+   *   }
+   * ]
+   * ```
+   */
+  iconPacks?: IconPack[];
 }
 
 /**

package/astro-mermaid-integration.js

@@ -65,7 +65,8 @@ export default function astroMermaid(options = {}) {
   const {
     theme = 'default',
     autoTheme = true,
-    mermaidConfig = {}
+    mermaidConfig = {},
+    iconPacks = []
   } = options;
 
   return {
@@ -92,129 +93,163 @@ export default function astroMermaid(options = {}) {
           }
         });
 
-        // Inject client-side mermaid script
-        const mermaidScriptContent = `
-import mermaid from 'mermaid';
-
-// Mermaid configuration
-const defaultConfig = ${JSON.stringify({
-  startOnLoad: false,
-  theme: theme,
-  ...mermaidConfig
-})};
+        // Serialize icon packs for client-side use
+        const iconPacksConfig = iconPacks.map(pack => ({
+          name: pack.name,
+          loader: pack.loader.toString()
+        }));
 
-// Theme mapping for auto-theme switching
-const themeMap = {
-  'light': 'default',
-  'dark': 'dark'
+        // Inject client-side mermaid script with conditional loading
+        const mermaidScriptContent = `
+// Check if page has mermaid diagrams
+const hasMermaidDiagrams = () => {
+  return document.querySelectorAll('pre.mermaid').length > 0;
 };
 
-// Initialize all mermaid diagrams
-async function initMermaid() {
-  console.log('[astro-mermaid] Initializing mermaid diagrams...');
-  const diagrams = document.querySelectorAll('pre.mermaid');
-  
-  console.log('[astro-mermaid] Found', diagrams.length, 'mermaid diagrams');
-  
-  if (diagrams.length === 0) {
-    console.log('[astro-mermaid] No mermaid diagrams found. Looking for code blocks...');
-    const codeBlocks = document.querySelectorAll('pre code.language-mermaid');
-    console.log('[astro-mermaid] Found', codeBlocks.length, 'mermaid code blocks');
-    return;
-  }
-  
-  // Get current theme
-  let currentTheme = defaultConfig.theme;
-  
-  if (${autoTheme}) {
-    const dataTheme = document.documentElement.getAttribute('data-theme');
-    currentTheme = themeMap[dataTheme] || defaultConfig.theme;
-    console.log('[astro-mermaid] Using theme:', currentTheme);
-  }
-  
-  // Configure mermaid
-  mermaid.initialize({
-    ...defaultConfig,
-    theme: currentTheme
-  });
+// Only proceed if there are mermaid diagrams on the page
+if (hasMermaidDiagrams()) {
+  console.log('[astro-mermaid] Mermaid diagrams detected, loading mermaid.js...');
   
-  // Render each diagram
-  for (const diagram of diagrams) {
-    // Skip if already processed
-    if (diagram.hasAttribute('data-processed')) continue;
-    
-    // Store original content
-    if (!diagram.hasAttribute('data-diagram')) {
-      diagram.setAttribute('data-diagram', diagram.textContent || '');
+  // Dynamically import mermaid only when needed
+  import('mermaid').then(async ({ default: mermaid }) => {
+    // Register icon packs if provided
+    const iconPacks = ${JSON.stringify(iconPacksConfig)};
+    if (iconPacks && iconPacks.length > 0) {
+      console.log('[astro-mermaid] Registering', iconPacks.length, 'icon packs');
+      const packs = iconPacks.map(pack => ({
+        name: pack.name,
+        loader: new Function('return ' + pack.loader)()
+      }));
+      await mermaid.registerIconPacks(packs);
     }
-    
-    const diagramDefinition = diagram.getAttribute('data-diagram') || '';
-    const id = 'mermaid-' + Math.random().toString(36).slice(2, 11);
-    
-    console.log('[astro-mermaid] Rendering diagram:', id);
-    
-    try {
-      const { svg } = await mermaid.render(id, diagramDefinition);
-      diagram.innerHTML = svg;
-      diagram.setAttribute('data-processed', 'true');
-      console.log('[astro-mermaid] Successfully rendered diagram:', id);
-    } catch (error) {
-      console.error('[astro-mermaid] Mermaid rendering error:', error);
-      diagram.innerHTML = '<div style="color: red;">Error rendering diagram</div>';
+    // Mermaid configuration
+    const defaultConfig = ${JSON.stringify({
+      startOnLoad: false,
+      theme: theme,
+      ...mermaidConfig
+    })};
+
+    // Theme mapping for auto-theme switching
+    const themeMap = {
+      'light': 'default',
+      'dark': 'dark'
+    };
+
+    // Initialize all mermaid diagrams
+    async function initMermaid() {
+      console.log('[astro-mermaid] Initializing mermaid diagrams...');
+      const diagrams = document.querySelectorAll('pre.mermaid');
+      
+      console.log('[astro-mermaid] Found', diagrams.length, 'mermaid diagrams');
+      
+      if (diagrams.length === 0) {
+        return;
+      }
+      
+      // Get current theme
+      let currentTheme = defaultConfig.theme;
+      
+      if (${autoTheme}) {
+        const dataTheme = document.documentElement.getAttribute('data-theme');
+        currentTheme = themeMap[dataTheme] || defaultConfig.theme;
+        console.log('[astro-mermaid] Using theme:', currentTheme);
+      }
+      
+      // Configure mermaid with gitGraph support
+      mermaid.initialize({
+        ...defaultConfig,
+        theme: currentTheme,
+        gitGraph: {
+          mainBranchName: 'main',
+          showCommitLabel: true,
+          showBranches: true,
+          rotateCommitLabel: true
+        }
+      });
+      
+      // Render each diagram
+      for (const diagram of diagrams) {
+        // Skip if already processed
+        if (diagram.hasAttribute('data-processed')) continue;
+        
+        // Store original content
+        if (!diagram.hasAttribute('data-diagram')) {
+          diagram.setAttribute('data-diagram', diagram.textContent || '');
+        }
+        
+        const diagramDefinition = diagram.getAttribute('data-diagram') || '';
+        const id = 'mermaid-' + Math.random().toString(36).slice(2, 11);
+        
+        console.log('[astro-mermaid] Rendering diagram:', id);
+        
+        try {
+          // Clear any existing error state
+          const existingGraph = document.getElementById(id);
+          if (existingGraph) {
+            existingGraph.remove();
+          }
+          
+          const { svg } = await mermaid.render(id, diagramDefinition);
+          diagram.innerHTML = svg;
+          diagram.setAttribute('data-processed', 'true');
+          console.log('[astro-mermaid] Successfully rendered diagram:', id);
+        } catch (error) {
+          console.error('[astro-mermaid] Mermaid rendering error for diagram:', id, error);
+          diagram.innerHTML = \`<div style="color: red; padding: 1rem; border: 1px solid red; border-radius: 0.5rem;">
+            <strong>Error rendering diagram:</strong><br/>
+            \${error.message || 'Unknown error'}
+          </div>\`;
+          diagram.setAttribute('data-processed', 'true');
+        }
+      }
     }
-  }
-}
 
-// Initialize on DOM ready
-if (document.readyState === 'loading') {
-  document.addEventListener('DOMContentLoaded', initMermaid);
-} else {
-  initMermaid();
-}
+    // Initialize immediately since DOM is ready
+    initMermaid();
 
-// Re-render on theme change if auto-theme is enabled
-if (${autoTheme}) {
-  const observer = new MutationObserver((mutations) => {
-    for (const mutation of mutations) {
-      if (mutation.type === 'attributes' && mutation.attributeName === 'data-theme') {
-        // Reset processed state and re-render
-        document.querySelectorAll('pre.mermaid[data-processed]').forEach(diagram => {
-          diagram.removeAttribute('data-processed');
-        });
+    // Re-render on theme change if auto-theme is enabled
+    if (${autoTheme}) {
+      const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          if (mutation.type === 'attributes' && mutation.attributeName === 'data-theme') {
+            // Reset processed state and re-render
+            document.querySelectorAll('pre.mermaid[data-processed]').forEach(diagram => {
+              diagram.removeAttribute('data-processed');
+            });
+            initMermaid();
+          }
+        }
+      });
+      
+      observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['data-theme']
+      });
+    }
+
+    // Handle view transitions (for Astro View Transitions API)
+    document.addEventListener('astro:after-swap', () => {
+      // Check again if new page has diagrams
+      if (hasMermaidDiagrams()) {
         initMermaid();
       }
-    }
-  });
-  
-  observer.observe(document.documentElement, {
-    attributes: true,
-    attributeFilter: ['data-theme']
+    });
+  }).catch(error => {
+    console.error('[astro-mermaid] Failed to load mermaid:', error);
   });
+} else {
+  console.log('[astro-mermaid] No mermaid diagrams found on this page, skipping mermaid.js load');
 }
-
-// Handle view transitions (for Astro View Transitions API)
-document.addEventListener('astro:after-swap', initMermaid);
 `;
 
         injectScript('page', mermaidScriptContent);
 
-        // Add CSS to the page
+        // Add CSS to the page with layout shift prevention
         injectScript('page', `
           // Add CSS for mermaid diagrams
           const style = document.createElement('style');
           style.textContent = \`
-            /* Hide diagrams until processed to prevent flash of unstyled content */
-            pre.mermaid:not([data-processed]) {
-              opacity: 0;
-              transition: opacity 0.3s ease-in-out;
-            }
-            
-            /* Show processed diagrams */
-            pre.mermaid[data-processed] {
-              opacity: 1;
-            }
-            
-            /* Center mermaid diagrams and add spacing */
+            /* Prevent layout shifts by setting minimum height */
             pre.mermaid {
               display: flex;
               justify-content: center;
@@ -224,6 +259,37 @@ document.addEventListener('astro:after-swap', initMermaid);
               background-color: transparent;
               border: none;
               overflow: auto;
+              min-height: 200px; /* Prevent layout shift */
+              position: relative;
+            }
+            
+            /* Loading state with skeleton loader */
+            pre.mermaid:not([data-processed]) {
+              background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+              background-size: 200% 100%;
+              animation: shimmer 1.5s infinite;
+            }
+            
+            /* Dark mode skeleton loader */
+            [data-theme="dark"] pre.mermaid:not([data-processed]) {
+              background: linear-gradient(90deg, #2a2a2a 25%, #3a3a3a 50%, #2a2a2a 75%);
+              background-size: 200% 100%;
+            }
+            
+            @keyframes shimmer {
+              0% {
+                background-position: -200% 0;
+              }
+              100% {
+                background-position: 200% 0;
+              }
+            }
+            
+            /* Show processed diagrams with smooth transition */
+            pre.mermaid[data-processed] {
+              animation: none;
+              background: transparent;
+              min-height: auto; /* Allow natural height after render */
             }
             
             /* Ensure responsive sizing for mermaid SVGs */
@@ -234,18 +300,29 @@ document.addEventListener('astro:after-swap', initMermaid);
             
             /* Optional: Add subtle background for better visibility */
             @media (prefers-color-scheme: dark) {
-              pre.mermaid {
+              pre.mermaid[data-processed] {
                 background-color: rgba(255, 255, 255, 0.02);
                 border-radius: 0.5rem;
               }
             }
             
             @media (prefers-color-scheme: light) {
-              pre.mermaid {
+              pre.mermaid[data-processed] {
                 background-color: rgba(0, 0, 0, 0.02);
                 border-radius: 0.5rem;
               }
             }
+            
+            /* Respect user's color scheme preference */
+            [data-theme="dark"] pre.mermaid[data-processed] {
+              background-color: rgba(255, 255, 255, 0.02);
+              border-radius: 0.5rem;
+            }
+            
+            [data-theme="light"] pre.mermaid[data-processed] {
+              background-color: rgba(0, 0, 0, 0.02);
+              border-radius: 0.5rem;
+            }
           \`;
           document.head.appendChild(style);
         `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-mermaid",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "An Astro integration for rendering Mermaid diagrams with automatic theme switching and client-side rendering",
   "type": "module",
   "main": "./astro-mermaid-integration.js",