astro-mermaid 1.0.3 → 1.1.0

package/README.md

@@ -1,47 +1,83 @@
 # astro-mermaid
 
-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)
+An Astro integration for rendering Mermaid diagrams with automatic theme switching, client-side rendering, and universal compatibility. Works seamlessly with both standalone Astro projects and documentation frameworks like Starlight.
+
+## Live Demos
+
+| Demo Type | URL | Description |
+|-----------|-----|-------------|
+| **Starlight Integration** | [starlight-mermaid-demo.netlify.app](https://starlight-mermaid-demo.netlify.app/) | Full documentation site with Starlight |
+| **Standalone Template** | [astro-mermaid-demo.netlify.app](https://astro-mermaid-demo.netlify.app/) | Pure Astro project template |
+
+Both demos showcase:
+- ✅ All diagram types with live examples
+- ✅ Theme switching (light/dark modes)  
+- ✅ Icon pack integration
+- ✅ Responsive design
+- ✅ Content collections and direct `.astro` usage
+
 
 ## Features
 
-- 🎨 Automatic theme switching based on your site's theme
-- 🚀 Client-side rendering for optimal performance
-- 📝 Simple markdown syntax using code blocks
-- ⚡ 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
+- 🎨 **Universal Theme Detection** - Works with both `html[data-theme]` and `body[data-theme]` attributes
+- 🚀 **Dual Plugin System** - Remark + Rehype plugins for comprehensive markdown processing  
+- 📝 **Universal File Support** - Works with `.md`, `.mdx`, and `.astro` files
+- ⚡ **Performance Optimized** - Conditional loading and client-side rendering
+- 🔧 **Highly Configurable** - Full mermaid.js configuration support
+- 🎯 **TypeScript Ready** - Complete type definitions included
+- 🔒 **Privacy-Focused** - No external dependencies, fully offline-capable
+- 📦 **Zero Configuration** - Works out of the box with sensible defaults
+- 🎭 **Smooth UX** - Loading animations and layout shift prevention
+- 🦌 **ELK Support** - Optionally works with the `elk` layout ([The Eclipse Layout Kernel](https://eclipse.dev/elk/))
 
-## Installation
+## Quick Start
+
+### 1. Installation
 
 ```bash
 npm install astro-mermaid mermaid
 ```
 
-## Usage
-
-Add the integration to your `astro.config.mjs`:
+### 2. Add to Astro Config
 
 ```js
+// astro.config.mjs
 import { defineConfig } from 'astro/config';
 import mermaid from 'astro-mermaid';
 
 export default defineConfig({
   integrations: [
     mermaid({
-      theme: 'forest'
+      theme: 'forest',
+      autoTheme: true
     })
   ]
 });
 ```
 
-### Important: Integration Order
+### 3. Use in Markdown
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+````
+
+### 4. (Optional) Use ELK layout
 
-When using with Starlight or other integrations that process markdown, make sure to place the mermaid integration **before** them:
+To enable the `elk` layout in Mermaid diagrams, install the `@mermaid-js/layout-elk` package.
+
+```bash
+npm install @mermaid-js/layout-elk
+```
+
+Learn more about [Mermaid layouts](https://mermaid.js.org/config/layouts.html) or [The Eclipse Layout Kernel](https://eclipse.dev/elk/).
+
+## Integration Order (Important!)
+
+When using with Starlight or other markdown-processing integrations, place mermaid **first**:
 
 ```js
 import { defineConfig } from 'astro/config';
@@ -50,7 +86,7 @@ import mermaid from 'astro-mermaid';
 
 export default defineConfig({
   integrations: [
-    mermaid(), // Must come BEFORE starlight
+    mermaid(), // ⚠️ Must come BEFORE starlight
     starlight({
       title: 'My Docs'
     })
@@ -58,18 +94,6 @@ export default defineConfig({
 });
 ```
 
-Then use mermaid code blocks in your markdown files:
-
-````markdown
-```mermaid
-graph TD
-    A[Start] --> B{Is it working?}
-    B -->|Yes| C[Great!]
-    B -->|No| D[Debug]
-    D --> A
-```
-````
-
 ## Configuration
 
 ```js
@@ -192,14 +216,16 @@ All mermaid diagram types are supported:
 - Quadrant charts
 - And more!
 
-## Demo
+## Version
+
+**Current:** `v1.0.4` - Enhanced universal compatibility with dual plugin system
 
-Check out the [live demo](https://starlight-mermaid-demo.netlify.app/) built with Starlight.
+See [changelog](https://github.com/joesaby/astro-mermaid/releases) for version history.
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions welcome! See our [demos](https://astro-mermaid-demo.netlify.app/) for examples.
 
 ## License
 
-MIT
+MIT © [Jose Sebastian](https://github.com/joesaby)

package/astro-mermaid-integration.js

@@ -1,5 +1,40 @@
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
+import { resolve } from 'import-meta-resolve';
+
+/**
+ * Remark plugin to transform mermaid code blocks at the markdown level
+ */
+function remarkMermaidPlugin(options = {}) {
+  return async function transformer(tree, file) {
+    const { visit } = await import('unist-util-visit');
+
+    let mermaidCount = 0;
+
+    visit(tree, 'code', (node, index, parent) => {
+      if (node.lang === 'mermaid') {
+        mermaidCount++;
+
+        // Transform to html node with pre.mermaid
+        const htmlNode = {
+          type: 'html',
+          value: `<pre class="mermaid">${node.value}</pre>`
+        };
+
+        // Replace the code node with html node
+        if (parent && typeof index === 'number') {
+          parent.children[index] = htmlNode;
+        }
+
+        if (options.logger) {
+          options.logger.info(`Remark transformed mermaid block #${mermaidCount} in ${file.path || 'unknown file'}`);
+        }
+      }
+    });
+
+    if (mermaidCount > 0 && options.logger) {
+      options.logger.info(`Remark total mermaid blocks transformed: ${mermaidCount}`);
+    }
+  };
+}
 
 /**
  * Rehype plugin to transform mermaid code blocks
@@ -9,9 +44,9 @@ function rehypeMermaidPlugin(options = {}) {
   return async function transformer(tree, file) {
     const { visit } = await import('unist-util-visit');
     const { toString } = await import('mdast-util-to-string');
-    
+
     let mermaidCount = 0;
-    
+
     visit(tree, 'element', (node, index, parent) => {
       // Look for <pre><code class="language-mermaid">
       if (
@@ -21,40 +56,52 @@ function rehypeMermaidPlugin(options = {}) {
       ) {
         const codeNode = node.children[0];
         const className = codeNode.properties?.className;
-        
+
         if (Array.isArray(className) && className.includes('language-mermaid')) {
           mermaidCount++;
           // Get the mermaid diagram content
           const diagramContent = toString(codeNode);
-          
+
           // Transform to <pre class="mermaid">
           node.properties = {
             ...node.properties,
             className: ['mermaid']
           };
-          
+
           node.children = [{
             type: 'text',
             value: diagramContent
           }];
-          
+
           if (options.logger) {
-            options.logger.info(`Transformed mermaid block #${mermaidCount} in ${file.path || 'unknown file'}`);
+            options.logger.info(`Rehype transformed mermaid block #${mermaidCount} in ${file.path || 'unknown file'}`);
           }
         }
       }
     });
-    
+
     if (mermaidCount > 0 && options.logger) {
-      options.logger.info(`Total mermaid blocks transformed: ${mermaidCount}`);
+      options.logger.info(`Rehype total mermaid blocks transformed: ${mermaidCount}`);
     }
   };
 }
 
+/** Detect if optional peer dependency `@mermaid-js/layout-elk` is available. */
+async function isElkInstalled(logger, consumerRoot) {
+  try {
+    resolve('@mermaid-js/layout-elk', `${consumerRoot.href}package.json`);
+    logger.info('Enabling ELK support');
+    return true;
+  } catch {
+    logger.info('Skipping ELK support');
+    return false;
+  }
+}
+
 /**
  * Astro integration for rendering Mermaid diagrams
  * Supports automatic theme switching and client-side rendering
- * 
+ *
  * @param {Object} options - Configuration options
  * @param {string} [options.theme='default'] - Default theme ('default', 'dark', 'forest', 'neutral')
  * @param {boolean} [options.autoTheme=true] - Enable automatic theme switching based on data-theme attribute
@@ -78,9 +125,22 @@ export default function astroMermaid(options = {}) {
         // Log existing rehype plugins
         logger.info('Existing rehype plugins:', config.markdown?.rehypePlugins?.length || 0);
 
-        // Update markdown config to use our rehype plugin
+        // Always include mermaid.
+        const viteOptimizeDepsInclude = ['mermaid'];
+        
+        // Conditionally include ELK
+        const useElk = await isElkInstalled(logger, config.root);
+        if (useElk) {
+          viteOptimizeDepsInclude.push('@mermaid-js/layout-elk');
+        }
+
+        // Update markdown config to use both remark and rehype plugins
         updateConfig({
           markdown: {
+            remarkPlugins: [
+              ...(config.markdown?.remarkPlugins || []),
+              [remarkMermaidPlugin, { logger }]
+            ],
             rehypePlugins: [
               ...(config.markdown?.rehypePlugins || []),
               [rehypeMermaidPlugin, { logger }]
@@ -88,7 +148,7 @@ export default function astroMermaid(options = {}) {
           },
           vite: {
             optimizeDeps: {
-              include: ['mermaid']
+              include: viteOptimizeDepsInclude
             }
           }
         });
@@ -122,6 +182,16 @@ if (hasMermaidDiagrams()) {
       }));
       await mermaid.registerIconPacks(packs);
     }
+
+    // Register ELK layouts if the optional peer is available at build-time
+    ${useElk ? `
+const elkModule = await import("@mermaid-js/layout-elk").catch(() => null);
+if (elkModule?.default) {
+  console.log("[astro-mermaid] Registering elk layouts");
+  mermaid.registerLayoutLoaders(elkModule.default);
+}
+` : ``}
+
     // Mermaid configuration
     const defaultConfig = ${JSON.stringify({
       startOnLoad: false,
@@ -146,13 +216,16 @@ if (hasMermaidDiagrams()) {
         return;
       }
       
-      // Get current theme
+      // Get current theme from multiple sources
       let currentTheme = defaultConfig.theme;
       
       if (${autoTheme}) {
-        const dataTheme = document.documentElement.getAttribute('data-theme');
+        // Check both html and body for data-theme attribute
+        const htmlTheme = document.documentElement.getAttribute('data-theme');
+        const bodyTheme = document.body.getAttribute('data-theme');
+        const dataTheme = htmlTheme || bodyTheme;
         currentTheme = themeMap[dataTheme] || defaultConfig.theme;
-        console.log('[astro-mermaid] Using theme:', currentTheme);
+        console.log('[astro-mermaid] Using theme:', currentTheme, 'from', htmlTheme ? 'html' : 'body');
       }
       
       // Configure mermaid with gitGraph support
@@ -221,10 +294,15 @@ if (hasMermaidDiagrams()) {
         }
       });
       
+      // Observe both html and body for data-theme changes
       observer.observe(document.documentElement, {
         attributes: true,
         attributeFilter: ['data-theme']
       });
+      observer.observe(document.body, {
+        attributes: true,
+        attributeFilter: ['data-theme']
+      });
     }
 
     // Handle view transitions (for Astro View Transitions API)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-mermaid",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "An Astro integration for rendering Mermaid diagrams with automatic theme switching and client-side rendering",
   "type": "module",
   "main": "./astro-mermaid-integration.js",
@@ -29,10 +29,17 @@
   "author": "Jose Sebastian",
   "license": "MIT",
   "peerDependencies": {
+    "@mermaid-js/layout-elk": "^0.2.0",
     "astro": "^4.0.0 || ^5.0.0",
     "mermaid": "^10.0.0 || ^11.0.0"
   },
+  "peerDependenciesMeta": {
+    "@mermaid-js/layout-elk": {
+      "optional": true
+    }
+  },
   "dependencies": {
+    "import-meta-resolve": "^4.2.0",
     "mdast-util-to-string": "^4.0.0",
     "unist-util-visit": "^5.0.0"
   },
@@ -44,7 +51,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/joesaby/astro-mermaid.git"
+    "url": "git+https://github.com/joesaby/astro-mermaid.git"
   },
   "homepage": "https://github.com/joesaby/astro-mermaid#readme",
   "bugs": {