feat: add Mermaid.js support for diagram rendering on GitHub Pages (#86)

* docs: improve documentation structure with unified command chains and cross-linking (#79)

Co-authored-by: Dominikus Nold <[email protected]>

* docs: add integrations overview guide (optional task 6.4)

- Create integrations-overview.md with comprehensive overview of all integrations
- Add links from integration guides to integrations-overview.md
- Add link to integrations-overview.md in docs/README.md
- Complete optional task 6.4 from improve-documentation-structure change

* docs: fix linting errors in integrations-overview.md

- Fix MD036 warnings by converting emphasis to proper headings
- Fix MD040 warning by adding language specifier to code block

* docs: simplify README and add links to new documentation

- Update website links to specfact.com / .io / .dev
- Add GitHub Pages docs link: https://nold-ai.github.io/specfact-cli/
- Remove version info section (avoids outdated info)
- Simplify content - remove verbose sections, add links to docs instead
- Add links to new documentation:
  - Command Chains Reference
  - Common Tasks Quick Reference
  - AI IDE Workflow Guide
  - Integrations Overview
- Improve onboarding with clear path for new users

* docs: add prominent SpecFact domain links with context

- Add specfact.com, specfact.io, specfact.dev links prominently at top
- Add domain purpose context (commercial, ecosystem, developer community)
- Highlight specfact.dev for developers
- Add GitHub Pages docs link
- Improve user navigation to appropriate resources

* docs: update Quick Start with correct IDE setup workflow

- Add Step 2: Initialize IDE integration (specfact init --ide)
- Update Step 3: Use slash commands in IDE or CLI
- Add realistic timing expectations (10-15 min for typical repos)
- Explain what init does (copies prompts, makes slash commands available)
- Add link to AI IDE Workflow Guide
- Remove unrealistic '60 seconds' claim

* fix: correct heading level for SpecFact Domains section

* docs: fix GitHub Pages permalinks for all documentation pages

- Update permalinks to include full directory path (e.g., /reference/commands/ instead of /commands/)
- Add frontmatter with permalinks to agile-scrum-workflows.md and reference/README.md
- Add frontmatter with permalink to speckit-journey.md for consistency
- All permalinks now match the Jekyll configuration pattern
- Enables proper GitHub Pages URLs for platform-frontend sites

* fix: resolve Jekyll build errors for GitHub Pages

- Quote title in speckit-journey.md frontmatter to fix YAML parsing error
- Wrap Jinja2 template code in {% raw %} tags in agile-scrum-workflows.md
  to prevent Jekyll from parsing it as Liquid syntax

Fixes GitHub Pages build errors:
- YAML Exception in speckit-journey.md (line 3)
- Liquid syntax error in agile-scrum-workflows.md (line 708)

* docs: add new pages to GitHub Pages navigation menu

- Add Command Chains to Guides section
- Add Agile/Scrum Workflows to Guides section
- Add Reference Documentation index to Reference section

These pages were missing from the navigation menu after fixing permalinks.

* docs: add new pages to GitHub Pages sidebar navigation menu

- Add Command Chains to Guides section (top of list)
- Add Agile/Scrum Workflows to Guides section
- Add Reference Documentation index to Reference section
- Fix reference links to use correct permalinks (/reference/architecture/, etc.)

The sidebar navigation menu is hardcoded in the layout file, so these
pages need to be manually added to appear in the left sidebar.

* feat: add Mermaid.js support for diagram rendering on GitHub Pages

- Add Mermaid.js CDN script to layout
- Add JavaScript to convert mermaid code blocks to renderable divs
- Handle kramdown output format (pre > code.language-mermaid)
- Initialize Mermaid with proper configuration

Fixes Mermaid diagram rendering on GitHub Pages documentation.
All mermaid code blocks will now render as interactive diagrams.

---------

Co-authored-by: Dominikus Nold <[email protected]>

Author: djm81

docs/_layouts/default.html

@@ -10,6 +10,39 @@
     {% if jekyll.environment == 'production' and site.google_analytics %}
     {% include google-analytics.html %}
     {% endif %}
+    <!-- Mermaid.js for diagram rendering -->
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+    <script>
+      document.addEventListener('DOMContentLoaded', function() {
+        // Find all mermaid code blocks (kramdown outputs: <pre><code class="language-mermaid">)
+        const mermaidCodeBlocks = document.querySelectorAll('pre code.language-mermaid, code.language-mermaid');
+        
+        mermaidCodeBlocks.forEach(function(codeBlock) {
+          const pre = codeBlock.closest('pre');
+          const mermaidCode = codeBlock.textContent || codeBlock.innerText;
+          
+          // Create mermaid div
+          const mermaidDiv = document.createElement('div');
+          mermaidDiv.className = 'mermaid';
+          mermaidDiv.textContent = mermaidCode.trim();
+          
+          // Replace the entire pre block (or just the code if no pre)
+          if (pre) {
+            pre.parentNode.replaceChild(mermaidDiv, pre);
+          } else {
+            codeBlock.parentNode.replaceChild(mermaidDiv, codeBlock);
+          }
+        });
+        
+        // Initialize Mermaid after converting all blocks
+        mermaid.initialize({ 
+          startOnLoad: true,
+          theme: 'default',
+          securityLevel: 'loose',
+          flowchart: { useMaxWidth: true }
+        });
+      });
+    </script>
   </head>
   <body>
     <header class="site-header" role="banner">