astro-mermaid 1.0.4 → 1.2.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,19 @@
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
+import { resolve } from 'import-meta-resolve';
+
+/**
+ * Helper function to HTML-escape text content
+ * This ensures HTML tags in mermaid diagrams are preserved as text
+ */
+function escapeHtml(text) {
+  const htmlEntities = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;'
+  };
+  return text.replace(/[&<>"']/g, char => htmlEntities[char]);
+}
 
 /**
  * Remark plugin to transform mermaid code blocks at the markdown level
@@ -7,36 +21,79 @@ import path from 'node:path';
 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
+
+        // Transform to html node with pre.mermaid, escaping HTML content
         const htmlNode = {
           type: 'html',
-          value: `<pre class="mermaid">${node.value}</pre>`
+          value: `<pre class="mermaid">${escapeHtml(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}`);
     }
   };
 }
 
+/**
+ * Helper function to serialize HAST nodes back to HTML text
+ * This preserves HTML tags within the mermaid content
+ */
+function serializeHastChildren(children) {
+  let result = '';
+
+  for (const child of children) {
+    if (child.type === 'text') {
+      result += child.value;
+    } else if (child.type === 'element') {
+      // Reconstruct the HTML tag
+      const tagName = child.tagName;
+      const selfClosing = ['br', 'hr', 'img', 'input', 'meta', 'link'].includes(tagName);
+
+      result += `<${tagName}`;
+
+      // Add attributes if any
+      if (child.properties) {
+        for (const [key, value] of Object.entries(child.properties)) {
+          if (key !== 'className') {
+            result += ` ${key}="${value}"`;
+          } else if (Array.isArray(value)) {
+            result += ` class="${value.join(' ')}"`;
+          }
+        }
+      }
+
+      if (selfClosing) {
+        result += '/>';
+      } else {
+        result += '>';
+        if (child.children && child.children.length > 0) {
+          result += serializeHastChildren(child.children);
+        }
+        result += `</${tagName}>`;
+      }
+    }
+  }
+
+  return result;
+}
+
 /**
  * Rehype plugin to transform mermaid code blocks
  * Converts ```mermaid code blocks to <pre class="mermaid">
@@ -44,10 +101,9 @@ function remarkMermaidPlugin(options = {}) {
 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 (
@@ -57,40 +113,53 @@ 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);
-          
+          // Get the mermaid diagram content, preserving HTML tags
+          const diagramContent = serializeHastChildren(codeNode.children || []);
+
           // Transform to <pre class="mermaid">
           node.properties = {
             ...node.properties,
             className: ['mermaid']
           };
-          
+
+          // Escape HTML to preserve it as text content
           node.children = [{
             type: 'text',
-            value: diagramContent
+            value: escapeHtml(diagramContent)
           }];
-          
+
           if (options.logger) {
             options.logger.info(`Rehype transformed mermaid block #${mermaidCount} in ${file.path || 'unknown file'}`);
           }
         }
       }
     });
-    
+
     if (mermaidCount > 0 && options.logger) {
       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
@@ -114,6 +183,15 @@ export default function astroMermaid(options = {}) {
         // Log existing rehype plugins
         logger.info('Existing rehype plugins:', config.markdown?.rehypePlugins?.length || 0);
 
+        // 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: {
@@ -128,7 +206,7 @@ export default function astroMermaid(options = {}) {
           },
           vite: {
             optimizeDeps: {
-              include: ['mermaid']
+              include: viteOptimizeDepsInclude
             }
           }
         });
@@ -162,6 +240,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-mermaid",
-  "version": "1.0.4",
+  "version": "1.2.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,25 +29,47 @@
   "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": {
+    "@anthropic-ai/claude-code": "^1.0.128",
+    "import-meta-resolve": "^4.2.0",
     "mdast-util-to-string": "^4.0.0",
     "unist-util-visit": "^5.0.0"
   },
+  "scripts": {
+    "claude": "claude",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage"
+  },
   "devDependencies": {
     "@types/hast": "^3.0.4",
+    "@vitest/ui": "^3.2.4",
     "astro": "^5.0.0",
+    "hast-util-from-html": "^2.0.3",
     "mermaid": "^11.0.0",
-    "typescript": "^5.0.0"
+    "rehype-parse": "^9.0.1",
+    "rehype-stringify": "^10.0.1",
+    "remark-mermaid": "^0.2.0",
+    "remark-parse": "^11.0.0",
+    "typescript": "^5.0.0",
+    "unified": "^11.0.5",
+    "vitest": "^3.2.4"
   },
   "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": {
     "url": "https://github.com/joesaby/astro-mermaid/issues"
   }
-}
+}