diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index e1c78384..de93e85c 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -12,22 +12,16 @@
   <link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
   
   <!-- Mermaid for diagram rendering -->
-  <script src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js"></script>
-  <script>
-    // Configure Mermaid before it initializes
-    window.mermaidConfig = {
-      startOnLoad: false,
-      theme: 'dark',
-      securityLevel: 'loose'
-    };
-  </script>
+  <script defer src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js"></script>
 </head>
 <body>
   <div class="main-content">
     {{ content }}
   </div>
   
+  <!-- Mermaid initialization script -->
+  <script defer src="{{ '/assets/js/mermaid-init.js' | relative_url }}"></script>
   <!-- Custom scripts -->
-  <script src="{{ '/assets/js/custom.js' | relative_url }}"></script>
+  <script defer src="{{ '/assets/js/custom.js' | relative_url }}"></script>
 </body>
 </html>
\ No newline at end of file
diff --git a/docs/assets/js/custom.js b/docs/assets/js/custom.js
index 5b72c0ba..62dca638 100644
--- a/docs/assets/js/custom.js
+++ b/docs/assets/js/custom.js
@@ -1,86 +1,7 @@
 // Smart Elections Parser - Documentation JavaScript
-// Ensures Mermaid graphs render and adds theme enhancements
-
-/**
- * Convert fenced code blocks (```mermaid) to Mermaid-compatible div elements.
- * Jekyll/GitHub Pages converts ```mermaid blocks to <pre><code class="language-mermaid">
- * but Mermaid.js expects <div class="mermaid"> elements.
- */
-function convertMermaidCodeBlocks() {
-  // Find all code blocks with language-mermaid class
-  const codeBlocks = document.querySelectorAll('pre > code.language-mermaid');
-  
-  codeBlocks.forEach((codeBlock) => {
-    const pre = codeBlock.parentElement;
-    const parent = pre.parentNode;
-    
-    // Safety check: ensure pre is still in the DOM
-    if (!parent) return;
-    
-    // Create a new div with mermaid class
-    const mermaidDiv = document.createElement('div');
-    mermaidDiv.className = 'mermaid';
-    // Get the text content (the Mermaid diagram definition)
-    mermaidDiv.textContent = codeBlock.textContent;
-    
-    // Replace the <pre><code> with the mermaid div
-    parent.replaceChild(mermaidDiv, pre);
-  });
-}
-
-// Wait for Mermaid to load, then initialize
-function initializeMermaid() {
-  if (typeof mermaid !== 'undefined') {
-    // First, convert fenced code blocks to mermaid divs
-    convertMermaidCodeBlocks();
-    
-    mermaid.initialize({
-      startOnLoad: false,
-      theme: 'dark',
-      themeVariables: {
-        primaryColor: '#45818e',
-        primaryTextColor: '#e6e8ea',
-        primaryBorderColor: '#00ffe7',
-        lineColor: '#00ffe7',
-        secondaryColor: '#1a232a',
-        tertiaryColor: '#eb4f43',
-        background: '#1a232a',
-        mainBkg: '#1a232a',
-        secondBkg: '#2a3440',
-        border1: '#00ffe7',
-        border2: '#45818e',
-        arrowheadColor: '#00ffe7',
-        fontFamily: '"Segoe UI", system-ui, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Arial, sans-serif',
-        fontSize: '14px'
-      },
-      flowchart: {
-        useMaxWidth: true,
-        htmlLabels: true,
-        curve: 'basis'
-      },
-      sequence: {
-        useMaxWidth: true
-      },
-      gantt: {
-        useMaxWidth: true
-      },
-      securityLevel: 'loose'
-    });
-
-    // Run mermaid on all .mermaid elements
-    mermaid.run({
-      querySelector: '.mermaid'
-    });
-  } else {
-    // Retry if Mermaid not loaded yet
-    setTimeout(initializeMermaid, 100);
-  }
-}
+// Adds theme enhancements and interactive features
 
 document.addEventListener('DOMContentLoaded', function() {
-  // Initialize Mermaid with retry logic
-  initializeMermaid();
-
   // Add metallic glow effects to interactive elements
   const addGlowEffect = (element) => {
     element.addEventListener('mouseenter', function() {
@@ -98,6 +19,7 @@ document.addEventListener('DOMContentLoaded', function() {
   document.querySelectorAll('a, button, .breadcrumb-item a').forEach(addGlowEffect);
 
   // Enhance code blocks with copy functionality
+  // Note: Mermaid code blocks are converted to divs by mermaid-init.js, so we don't need to filter them
   document.querySelectorAll('pre').forEach(function(pre) {
     const button = document.createElement('button');
     button.textContent = '📋 Copy';
diff --git a/docs/assets/js/mermaid-init.js b/docs/assets/js/mermaid-init.js
new file mode 100644
index 00000000..09934257
--- /dev/null
+++ b/docs/assets/js/mermaid-init.js
@@ -0,0 +1,92 @@
+// Mermaid initialization script for GitHub Pages
+// Converts fenced mermaid code blocks to mermaid divs and initializes Mermaid.js
+
+/**
+ * Convert fenced code blocks (```mermaid) to Mermaid-compatible div elements.
+ * Jekyll/GitHub Pages converts ```mermaid blocks to <pre><code class="language-mermaid">
+ * but Mermaid.js expects <div class="mermaid"> elements.
+ */
+function convertMermaidCodeBlocks() {
+  // Find all code blocks with language-mermaid class
+  const codeBlocks = document.querySelectorAll('pre > code.language-mermaid');
+
+  codeBlocks.forEach((codeBlock) => {
+    const pre = codeBlock.parentElement;
+    const parent = pre.parentNode;
+
+    // Safety check: ensure pre is still in the DOM
+    if (!parent) return;
+
+    // Create a new div with mermaid class
+    const mermaidDiv = document.createElement('div');
+    mermaidDiv.className = 'mermaid';
+    // Get the text content (the Mermaid diagram definition)
+    mermaidDiv.textContent = codeBlock.textContent;
+
+    // Replace the <pre><code> with the mermaid div
+    parent.replaceChild(mermaidDiv, pre);
+  });
+}
+
+/**
+ * Initialize Mermaid with proper configuration and render all diagrams.
+ * Includes retry logic with maximum attempts in case Mermaid hasn't loaded yet.
+ */
+var mermaidRetryCount = 0;
+var mermaidMaxRetries = 50; // Max 5 seconds of retries (50 * 100ms)
+
+function initializeMermaid() {
+  if (typeof mermaid !== 'undefined') {
+    // First, convert fenced code blocks to mermaid divs
+    convertMermaidCodeBlocks();
+
+    mermaid.initialize({
+      startOnLoad: false,
+      theme: 'dark',
+      themeVariables: {
+        primaryColor: '#45818e',
+        primaryTextColor: '#e6e8ea',
+        primaryBorderColor: '#00ffe7',
+        lineColor: '#00ffe7',
+        secondaryColor: '#1a232a',
+        tertiaryColor: '#eb4f43',
+        background: '#1a232a',
+        mainBkg: '#1a232a',
+        secondBkg: '#2a3440',
+        border1: '#00ffe7',
+        border2: '#45818e',
+        arrowheadColor: '#00ffe7',
+        fontFamily: '"Segoe UI", system-ui, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Arial, sans-serif',
+        fontSize: '14px'
+      },
+      flowchart: {
+        useMaxWidth: true,
+        htmlLabels: true,
+        curve: 'basis'
+      },
+      sequence: {
+        useMaxWidth: true
+      },
+      gantt: {
+        useMaxWidth: true
+      },
+      securityLevel: 'loose'
+    });
+
+    // Run mermaid on all .mermaid elements
+    mermaid.run({
+      querySelector: '.mermaid'
+    });
+  } else if (mermaidRetryCount < mermaidMaxRetries) {
+    // Retry if Mermaid not loaded yet, with a limit
+    mermaidRetryCount++;
+    setTimeout(initializeMermaid, 100);
+  } else {
+    console.warn('Mermaid library failed to load after maximum retries');
+  }
+}
+
+// Wait for DOM to be ready, then initialize Mermaid
+document.addEventListener('DOMContentLoaded', function() {
+  initializeMermaid();
+});
diff --git a/docs/pipeline_map.md b/docs/pipeline_map.md
index 622f61b5..0085af00 100644
--- a/docs/pipeline_map.md
+++ b/docs/pipeline_map.md
@@ -1,3 +1,8 @@
+---
+layout: default
+title: "Comprehensive Pipeline Audit & Map"
+---
+
 # Comprehensive Pipeline Audit & Map
 
 ## 📋 Table of Contents
diff --git a/docs/project_audit.md b/docs/project_audit.md
index a547b66d..8d610f9f 100644
--- a/docs/project_audit.md
+++ b/docs/project_audit.md
@@ -1,3 +1,8 @@
+---
+layout: default
+title: "Project Audit"
+---
+
 # Project Audit — webapp
 
 Modules scanned: 98 | ~53870 non-empty LOC
