@knowcode/doc-builder 1.4.8 → 1.4.10

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to @knowcode/doc-builder will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.10] - 2025-07-21
+
+### Fixed
+- Fixed mermaid diagram rendering by preventing HTML escaping of diagram content
+- Implemented placeholder system to protect mermaid blocks from markdown parser interference
+- Mermaid diagrams now render correctly without "Syntax error" messages
+
+### Background
+- Mermaid content was being HTML-escaped (e.g., `-->` became `-->`)
+- Markdown parser was breaking up mermaid blocks by interpreting indented lines as code blocks
+- Fixed by processing mermaid blocks before markdown parsing and using placeholders
+
+## [1.4.9] - 2025-07-21
+
+### Fixed
+- Fixed sidebar resizing issue where menu overlapped content instead of pushing it
+- Changed sidebar from `position: fixed` to `position: relative` to work properly with flexbox layout
+- Added `flex-shrink: 0` to sidebar to prevent shrinking
+- Removed unnecessary banner-specific positioning adjustments
+
+### Background
+- The sidebar was using fixed positioning which took it out of document flow
+- This caused the resize handle to only change sidebar width without affecting content position
+- With relative positioning and flexbox, the content now properly adjusts when sidebar is resized
+
 ## [1.4.8] - 2025-07-21
 
 ### Fixed

package/README.md

@@ -41,6 +41,7 @@ This aligns perfectly with our mission: beautiful documentation should be access
 - 🔄 **Live Reload** - Development server with hot reloading
 - ☁️ **Vercel Integration** - One-command deployment to Vercel
 - 📦 **Self-Contained** - No configuration or setup required
+- 🤖 **Claude Code Ready** - Optimized for AI-generated documentation workflows
 
 ## Quick Start
 
@@ -221,6 +222,50 @@ my-project/
 └── package.json
 ```
 
+## Working with Claude Code
+
+Many users leverage Claude Code to create and maintain their documentation. Claude Code is particularly effective at:
+
+### Generating Documentation
+Claude Code can analyze your codebase and automatically generate comprehensive documentation:
+- API documentation from code comments and function signatures
+- User guides based on your application structure
+- Installation and setup instructions
+- Troubleshooting guides
+
+### Documentation Conventions
+When using Claude Code to generate documentation, it typically follows these patterns:
+- Creates properly structured markdown files with hierarchical headings
+- Includes code examples with syntax highlighting
+- Generates Mermaid diagrams for visual representations
+- Follows consistent naming conventions (e.g., `component-guide.md`, `api-reference.md`)
+- Adds metadata headers for document tracking
+
+### Example Claude Code Workflow
+1. **Initial Documentation Generation**
+   ```
+   "Create comprehensive API documentation for this project"
+   ```
+   Claude Code will scan your codebase and generate appropriate markdown files in your `docs/` directory.
+
+2. **Updating Documentation**
+   ```
+   "Update the API documentation to reflect the new authentication methods"
+   ```
+   Claude Code will modify existing files while preserving structure and formatting.
+
+3. **Adding Visual Documentation**
+   ```
+   "Add a Mermaid diagram showing the application architecture"
+   ```
+   Claude Code will create diagrams that are automatically rendered by doc-builder.
+
+### Best Practices with Claude Code
+- **Structured Requests**: Be specific about what documentation you need
+- **Iterative Updates**: Claude Code can update existing docs without starting from scratch
+- **Review Generated Content**: Always review AI-generated documentation for accuracy
+- **Maintain CLAUDE.md**: Keep project-specific instructions in a CLAUDE.md file for consistent documentation style
+
 ## Using in Other Projects
 
 ### Option 1: NPM Link (Development)

package/assets/css/notion-style.css

@@ -311,27 +311,23 @@ pre code {
 
 /* Sidebar */
 .sidebar {
-  position: fixed;
-  left: 0;
-  top: calc(var(--header-height) + var(--breadcrumb-height));
-  bottom: 0;
+  position: relative;
   width: var(--sidebar-width);
   background: var(--color-bg-secondary);
   border-right: 1px solid var(--color-border-default);
   overflow: hidden;
-  transition: transform var(--duration-normal), top var(--duration-normal);
+  transition: width var(--duration-normal);
   min-width: 200px;
   max-width: 500px;
   user-select: none;
   display: flex;
   flex-direction: column;
   z-index: 100;
+  flex-shrink: 0;
+  height: 100%;
 }
 
-/* Adjust sidebar when banner is visible */
-.sidebar.banner-visible {
-  top: calc(var(--header-height) + var(--breadcrumb-height) + 3.5rem);
-}
+/* Banner adjustment no longer needed with relative positioning */
 
 
 .sidebar-home-link {

package/html/README.html

@@ -29,7 +29,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.4.7">Last updated: Jul 21, 2025, 11:18 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.4.9">Last updated: Jul 21, 2025, 12:05 PM UTC</span>
                 </div>
                 
                 
@@ -78,7 +78,8 @@
           <i class="fas fa-home"></i> Documentation
         </a>
         <div class="nav-content" >
-        <a href="/README.html" class="nav-item active" data-tooltip="This is a test document to verify the doc-builder version tooltip."><i class="fas fa-file-alt"></i> Overview</a></div></div>
+        <a href="/README.html" class="nav-item active" data-tooltip="This is a test document to verify the doc-builder version tooltip."><i class="fas fa-file-alt"></i> Overview</a>
+        <a href="/claude-workflow-guide.html" class="nav-item" data-tooltip="**Generated**: 2025-07-21 10:00 UTC **Status**: Complete **Verified**: ✅ This guide demonstrates an efficient workflow for using Claude Code with a re..."><i class="fas fa-file-alt"></i> Claude Workflow Guide</a></div></div>
             </nav>
             <div class="resize-handle"></div>
         </aside>

package/html/claude-workflow-guide.html

@@ -0,0 +1,450 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="Documentation site built with @knowcode/doc-builder">
+    <title>Claude + CLAUDE.md Documentation Workflow Guide - Documentation</title>
+    
+    <!-- Fonts -->
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+    
+    <!-- Icons -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
+    
+    <!-- Mermaid -->
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js"></script>
+    
+    <!-- Styles -->
+    <link rel="stylesheet" href="/css/notion-style.css">
+    
+    <!-- Favicon -->
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>📚</text></svg>">
+</head>
+<body>
+    <!-- Header -->
+    <header class="header">
+        <div class="header-content">
+            <a href="/index.html" class="logo">Documentation</a>
+            
+            <div class="header-actions">
+                <div class="deployment-info">
+                    <span class="deployment-date" title="Built with doc-builder v1.4.9">Last updated: Jul 21, 2025, 12:05 PM UTC</span>
+                </div>
+                
+                
+                
+                <button id="theme-toggle" class="theme-toggle" aria-label="Toggle theme">
+                    <i class="fas fa-moon"></i>
+                </button>
+                
+                <button id="menu-toggle" class="menu-toggle" aria-label="Toggle menu">
+                    <i class="fas fa-bars"></i>
+                </button>
+            </div>
+        </div>
+    </header>
+    
+    <!-- Preview Banner -->
+    <div id="preview-banner" class="preview-banner">
+        <div class="banner-content">
+            <i class="fas fa-exclamation-triangle banner-icon"></i>
+            <span class="banner-text">This documentation is a preview version - some content may be incomplete</span>
+            <button id="dismiss-banner" class="banner-dismiss" aria-label="Dismiss banner">
+                <i class="fas fa-times"></i>
+            </button>
+        </div>
+    </div>
+    
+    <!-- Breadcrumbs -->
+    <nav class="breadcrumbs" id="breadcrumbs">
+        <!-- Breadcrumbs will be generated by JavaScript -->
+    </nav>
+    
+    <!-- Main Content -->
+    <div class="main-wrapper">
+        <!-- Sidebar -->
+        <aside class="sidebar">
+            <div class="sidebar-header">
+                <div class="filter-box">
+                    <input type="text" placeholder="Filter items..." class="filter-input" id="nav-filter">
+                    <i class="fas fa-search filter-icon"></i>
+                </div>
+            </div>
+            <nav class="navigation">
+                
+      <div class="nav-section" data-level="0">
+        <a class="nav-title expanded" href="/README.html"  >
+          <i class="fas fa-home"></i> Documentation
+        </a>
+        <div class="nav-content" >
+        <a href="/README.html" class="nav-item" data-tooltip="This is a test document to verify the doc-builder version tooltip."><i class="fas fa-file-alt"></i> Overview</a>
+        <a href="/claude-workflow-guide.html" class="nav-item active" data-tooltip="**Generated**: 2025-07-21 10:00 UTC **Status**: Complete **Verified**: ✅ This guide demonstrates an efficient workflow for using Claude Code with a re..."><i class="fas fa-file-alt"></i> Claude Workflow Guide</a></div></div>
+            </nav>
+            <div class="resize-handle"></div>
+        </aside>
+        
+        <!-- Content Area -->
+        <main class="content">
+            <div class="content-inner">
+                <h1>Claude + CLAUDE.md Documentation Workflow Guide</h1>
+<p><strong>Generated</strong>: 2025-07-21 10:00 UTC<br><strong>Status</strong>: Complete<br><strong>Verified</strong>: ✅</p>
+<h2>Overview</h2>
+<p>This guide demonstrates an efficient workflow for using Claude Code with a refined CLAUDE.md file to create high-quality documentation and deploy it to Vercel using the @knowcode/doc-builder tool.</p>
+<h2>Workflow Overview</h2>
+<div class="mermaid-wrapper">
+      <div class="mermaid-title">Diagram</div>
+      <div class="mermaid">graph TD
+    A[Start Project] --> B[Setup CLAUDE.md]
+    B --> C[Configure doc-builder]
+    C --> D[Create Documentation with Claude]
+    D --> E[Build Static Site]
+    E --> F[Deploy to Vercel]
+    F --> G[Live Documentation]
+    
+    B -.-> H[Refine Instructions]
+    H -.-> D
+    
+    D --> I{Review Quality}
+    I -->|Needs Improvement| H
+    I -->|Good| E
+    
+    style A fill:#e1f5fe
+    style G fill:#c8e6c9
+    style H fill:#fff3e0</div>
+    </div>
+<h2>Step 1: Setting Up CLAUDE.md</h2>
+<h3>1.1 Project-Level CLAUDE.md</h3>
+<p>Create a <code>CLAUDE.md</code> file in your project root with specific instructions for documentation:</p>
+<pre><code class="language-markdown"># CLAUDE.md - [Your Project Name]
+
+## Documentation Standards
+
+### Document Structure
+- All documentation goes in the `/docs` directory
+- Use hierarchical folder structure for organization
+- Follow naming convention: `{component}-{topic}-guide.md`
+
+### Content Requirements
+- Include mermaid diagrams for complex workflows
+- Mark verified (✅) vs speculated (❓) information
+- Add timestamps to all documents
+- Include practical examples
+
+### Writing Style
+- Use clear, concise language
+- Target intermediate technical audience
+- Include code examples with syntax highlighting
+- Add troubleshooting sections
+
+### Metadata Format
+</code></pre>
+<p><strong>Generated</strong>: YYYY-MM-DD HH:MM UTC<br><strong>Status</strong>: Draft/Complete<br><strong>Verified</strong>: ✅/❓</p>
+<pre><code>
+</code></pre>
+<h3>1.2 Global CLAUDE.md Best Practices</h3>
+<p>Your global <code>~/.claude/CLAUDE.md</code> should include:</p>
+<div class="mermaid-wrapper">
+      <div class="mermaid-title">Diagram</div>
+      <div class="mermaid">graph LR
+    A[Global CLAUDE.md] --> B[Document Standards]
+    A --> C[Git Workflow]
+    A --> D[Quality Checks]
+    A --> E[Security Practices]
+    
+    B --> B1[Naming Conventions]
+    B --> B2[Markdown Standards]
+    B --> B3[Diagram Requirements]
+    
+    C --> C1[Commit Frequency]
+    C --> C2[Branch Strategy]
+    
+    D --> D1[Verification Marks]
+    D --> D2[Changelog Updates]
+    
+    E --> E1[No Credentials]
+    E --> E2[Access Controls]</div>
+    </div>
+<h2>Step 2: Initialize doc-builder</h2>
+<pre><code class="language-bash"># Install doc-builder
+npm install -D @knowcode/doc-builder
+
+# Initialize configuration
+npx doc-builder init
+</code></pre>
+<h3>2.1 Configure doc-builder.config.js</h3>
+<pre><code class="language-javascript">module.exports = {
+  siteName: &#39;Your Project Documentation&#39;,
+  siteDescription: &#39;Comprehensive documentation for Your Project&#39;,
+  docsDir: &#39;docs&#39;,
+  outputDir: &#39;html&#39;,
+  features: {
+    authentication: false,  // Set true for private docs
+    changelog: true,
+    mermaid: true,
+    darkMode: true
+  }
+};
+</code></pre>
+<h2>Step 3: Documentation Creation Workflow with Claude</h2>
+<h3>3.1 Effective Prompting Strategy</h3>
+<div class="mermaid-wrapper">
+      <div class="mermaid-title">Diagram</div>
+      <div class="mermaid">sequenceDiagram
+    participant User
+    participant Claude
+    participant CLAUDE.md
+    participant Documentation
+    
+    User->>Claude: Request documentation
+    Claude->>CLAUDE.md: Check project standards
+    CLAUDE.md-->>Claude: Return guidelines
+    Claude->>Documentation: Create/Update docs
+    Claude->>User: Confirm completion
+    User->>Claude: Review & refine
+    Claude->>Documentation: Apply refinements</div>
+    </div>
+<h3>3.2 Example Documentation Requests</h3>
+<h4>Initial Architecture Documentation</h4>
+<pre><code>&quot;Create comprehensive architecture documentation for our authentication system. Include:
+- System overview with mermaid diagrams
+- Component interactions
+- API endpoints
+- Security considerations
+- Deployment architecture&quot;
+</code></pre>
+<h4>API Documentation</h4>
+<pre><code>&quot;Document all REST API endpoints in our user service. For each endpoint include:
+- HTTP method and path
+- Request/response schemas
+- Authentication requirements
+- Example requests with curl
+- Error responses&quot;
+</code></pre>
+<h4>Setup Guide</h4>
+<pre><code>&quot;Create a detailed setup guide for new developers including:
+- Prerequisites
+- Environment setup steps
+- Configuration options
+- Common issues and solutions
+- Development workflow&quot;
+</code></pre>
+<h3>3.3 Claude Interaction Best Practices</h3>
+<ol>
+<li><strong>Be Specific</strong>: Provide clear requirements and expected structure</li>
+<li><strong>Iterate</strong>: Review generated content and request refinements</li>
+<li><strong>Verify</strong>: Ask Claude to mark verified vs speculated information</li>
+<li><strong>Examples</strong>: Request concrete examples and code snippets</li>
+<li><strong>Diagrams</strong>: Explicitly request mermaid diagrams for visual clarity</li>
+</ol>
+<h2>Step 4: Building Documentation Site</h2>
+<h3>4.1 Development Workflow</h3>
+<div class="mermaid-wrapper">
+      <div class="mermaid-title">Diagram</div>
+      <div class="mermaid">graph LR
+    A[Write Docs] --> B[Preview Locally]
+    B --> C{Looks Good?}
+    C -->|No| A
+    C -->|Yes| D[Build Site]
+    D --> E[Test Build]
+    E --> F{All Good?}
+    F -->|No| A
+    F -->|Yes| G[Ready to Deploy]
+    
+    style A fill:#fff3e0
+    style G fill:#c8e6c9</div>
+    </div>
+<h3>4.2 Commands</h3>
+<pre><code class="language-bash"># Start development server
+npm run dev:docs
+
+# Build static site
+npm run build:docs
+
+# Preview built site
+npx serve html
+</code></pre>
+<h2>Step 5: Deploying to Vercel</h2>
+<h3>5.1 First-Time Setup</h3>
+<pre><code class="language-bash"># Deploy to Vercel (interactive)
+npx doc-builder deploy
+
+# Or with npm script
+npm run deploy:docs
+</code></pre>
+<h3>5.2 Vercel Configuration</h3>
+<p>The tool automatically creates <code>vercel.json</code>:</p>
+<pre><code class="language-json">{
+  &quot;outputDirectory&quot;: &quot;html&quot;,
+  &quot;routes&quot;: [
+    {
+      &quot;src&quot;: &quot;/(.*)&quot;,
+      &quot;dest&quot;: &quot;/$1&quot;
+    }
+  ]
+}
+</code></pre>
+<h3>5.3 Deployment Workflow</h3>
+<div class="mermaid-wrapper">
+      <div class="mermaid-title">Diagram</div>
+      <div class="mermaid">stateDiagram-v2
+    [*] --> LocalDevelopment
+    LocalDevelopment --> BuildDocs: npm run build:docs
+    BuildDocs --> TestLocally: npx serve html
+    TestLocally --> Deploy: npx doc-builder deploy
+    Deploy --> VercelProcessing
+    VercelProcessing --> LiveSite: Success
+    VercelProcessing --> ErrorHandling: Failed
+    ErrorHandling --> LocalDevelopment: Fix issues
+    LiveSite --> [*]</div>
+    </div>
+<h2>Step 6: Continuous Documentation Updates</h2>
+<h3>6.1 Update Workflow</h3>
+<div class="mermaid-wrapper">
+      <div class="mermaid-title">Diagram</div>
+      <div class="mermaid">graph TD
+    A[Code Changes] --> B{Docs Needed?}
+    B -->|Yes| C[Update Documentation]
+    B -->|No| End[End]
+    C --> D[Use Claude for Updates]
+    D --> E[Review Changes]
+    E --> F[Build & Test]
+    F --> G[Deploy Updates]
+    G --> H[Update CHANGELOG.md]
+    H --> End
+    
+    style A fill:#ffebee
+    style G fill:#e8f5e9</div>
+    </div>
+<h3>6.2 Maintaining Documentation Quality</h3>
+<ol>
+<li><strong>Regular Reviews</strong>: Schedule periodic documentation reviews</li>
+<li><strong>Automated Checks</strong>: Add documentation linting to CI/CD</li>
+<li><strong>User Feedback</strong>: Create feedback mechanism for documentation</li>
+<li><strong>Version Tracking</strong>: Maintain documentation versions with code versions</li>
+</ol>
+<h2>Advanced CLAUDE.md Refinements</h2>
+<h3>7.1 Project-Specific Instructions</h3>
+<pre><code class="language-markdown">## Project-Specific Documentation Rules
+
+### Component Documentation
+- Each major component needs its own guide
+- Include architecture decisions
+- Document integration points
+- Add performance considerations
+
+### Code Examples
+- Use TypeScript for all examples
+- Include error handling
+- Show both correct and incorrect usage
+- Add inline comments for clarity
+
+### Diagrams
+- Use mermaid for all flow diagrams
+- Include sequence diagrams for APIs
+- Add state diagrams for complex logic
+- Create entity relationship diagrams for data models
+</code></pre>
+<h3>7.2 Documentation Templates</h3>
+<p>Create templates in your CLAUDE.md:</p>
+<pre><code class="language-markdown">## Documentation Templates
+
+### API Endpoint Template
+</code></pre>
+<h2>[HTTP Method] /api/[endpoint]</h2>
+<p><strong>Purpose</strong>: [Brief description]</p>
+<h3>Request</h3>
+<ul>
+<li><strong>Headers</strong>: <ul>
+<li><code>Authorization: Bearer [token]</code></li>
+<li><code>Content-Type: application/json</code></li>
+</ul>
+</li>
+<li><strong>Body</strong>:<pre><code class="language-json">{
+  &quot;field&quot;: &quot;value&quot;
+}
+</code></pre>
+</li>
+</ul>
+<h3>Response</h3>
+<ul>
+<li><strong>Success (200)</strong>:<pre><code class="language-json">{
+  &quot;data&quot;: {}
+}
+</code></pre>
+</li>
+<li><strong>Error (4xx/5xx)</strong>:<pre><code class="language-json">{
+  &quot;error&quot;: &quot;Description&quot;
+}
+</code></pre>
+</li>
+</ul>
+<h3>Examples</h3>
+<pre><code class="language-bash">curl -X POST https://api.example.com/endpoint \
+  -H &quot;Authorization: Bearer token&quot; \
+  -d &#39;{&quot;field&quot;: &quot;value&quot;}&#39;
+</code></pre>
+<pre><code>
+## Best Practices Summary
+
+### Documentation Creation
+1. ✅ Use CLAUDE.md to maintain consistency
+2. ✅ Include visual diagrams for complex concepts
+3. ✅ Provide practical examples
+4. ✅ Mark verification status
+5. ✅ Keep documentation close to code
+
+### Claude Interaction
+1. ✅ Provide clear, specific requests
+2. ✅ Reference existing patterns
+3. ✅ Request iterative improvements
+4. ✅ Verify technical accuracy
+5. ✅ Ask for troubleshooting sections
+
+### Deployment
+1. ✅ Test locally before deploying
+2. ✅ Use preview deployments first
+3. ✅ Configure custom domains
+4. ✅ Enable HTTPS
+5. ✅ Monitor deployment health
+
+## Common Issues and Solutions
+
+### Issue 1: Claude Not Following Standards
+**Solution**: Refine CLAUDE.md with more specific examples and explicit requirements
+
+### Issue 2: Documentation Build Fails
+**Solution**: Check markdown syntax, ensure all links are valid, verify mermaid syntax
+
+### Issue 3: Vercel Deployment Issues
+**Solution**: Check vercel.json configuration, ensure output directory is correct
+
+### Issue 4: Navigation Not Generated
+**Solution**: Verify folder structure follows conventions, check for special characters in filenames
+
+## Conclusion
+
+This workflow enables efficient, high-quality documentation creation by:
+- Leveraging Claude&#39;s capabilities with clear guidelines
+- Using doc-builder for beautiful, searchable output
+- Deploying seamlessly to Vercel for instant access
+- Maintaining consistency through CLAUDE.md refinements
+
+The key to success is iterative refinement of your CLAUDE.md file to capture your team&#39;s specific documentation needs and standards.
+
+## Document History
+
+| Date | Author | Changes |
+|------|--------|---------|
+| 2025-07-21 | Claude | Initial creation |
+</code></pre>
+
+            </div>
+        </main>
+    </div>
+    
+    <!-- Scripts -->
+    <script src="/js/main.js"></script>
+    
+</body>
+</html>

package/html/css/notion-style.css

@@ -311,27 +311,23 @@ pre code {
 
 /* Sidebar */
 .sidebar {
-  position: fixed;
-  left: 0;
-  top: calc(var(--header-height) + var(--breadcrumb-height));
-  bottom: 0;
+  position: relative;
   width: var(--sidebar-width);
   background: var(--color-bg-secondary);
   border-right: 1px solid var(--color-border-default);
   overflow: hidden;
-  transition: transform var(--duration-normal), top var(--duration-normal);
+  transition: width var(--duration-normal);
   min-width: 200px;
   max-width: 500px;
   user-select: none;
   display: flex;
   flex-direction: column;
   z-index: 100;
+  flex-shrink: 0;
+  height: 100%;
 }
 
-/* Adjust sidebar when banner is visible */
-.sidebar.banner-visible {
-  top: calc(var(--header-height) + var(--breadcrumb-height) + 3.5rem);
-}
+/* Banner adjustment no longer needed with relative positioning */
 
 
 .sidebar-home-link {

package/html/vercel.json

@@ -0,0 +1,29 @@
+{
+  "buildCommand": "",
+  "outputDirectory": ".",
+  "devCommand": "",
+  "installCommand": "",
+  "framework": null,
+  "cleanUrls": true,
+  "trailingSlash": false,
+  "headers": [
+    {
+      "source": "/css/(.*)",
+      "headers": [
+        {
+          "key": "Cache-Control",
+          "value": "public, max-age=31536000, immutable"
+        }
+      ]
+    },
+    {
+      "source": "/js/(.*)",
+      "headers": [
+        {
+          "key": "Cache-Control",
+          "value": "public, max-age=31536000, immutable"
+        }
+      ]
+    }
+  ]
+}

package/lib/core-builder.js

@@ -57,7 +57,9 @@ function extractSummary(content, maxLength = 150) {
 // Process markdown content
 function processMarkdownContent(content) {
   // Convert mermaid code blocks to mermaid divs with titles
-  content = content.replace(/```mermaid\n([\s\S]*?)```/g, (match, mermaidContent) => {
+  // Process before markdown parsing to prevent breaking up the content
+  const mermaidBlocks = [];
+  let processedContent = content.replace(/```mermaid\n([\s\S]*?)```/g, (match, mermaidContent) => {
     // Try to extract title from mermaid content
     let title = 'Diagram';
     
@@ -77,13 +79,25 @@ function processMarkdownContent(content) {
       }
     }
     
-    return `<div class="mermaid-wrapper">
+    // Store the mermaid block and return a placeholder
+    const placeholder = `MERMAID_BLOCK_${mermaidBlocks.length}`;
+    mermaidBlocks.push(`<div class="mermaid-wrapper">
       <div class="mermaid-title">${escapeHtml(title)}</div>
-      <div class="mermaid">${escapeHtml(mermaidContent)}</div>
-    </div>`;
+      <div class="mermaid">${mermaidContent.trim()}</div>
+    </div>`);
+    return placeholder;
+  });
+  
+  // Parse the markdown
+  let html = marked.parse(processedContent);
+  
+  // Replace placeholders with actual mermaid blocks
+  mermaidBlocks.forEach((block, index) => {
+    html = html.replace(`<p>MERMAID_BLOCK_${index}</p>`, block);
+    html = html.replace(`MERMAID_BLOCK_${index}`, block);
   });
   
-  return marked.parse(content);
+  return html;
 }
 
 // Generate HTML from template

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowcode/doc-builder",
-  "version": "1.4.8",
+  "version": "1.4.10",
   "description": "Reusable documentation builder for markdown-based sites with Vercel deployment support",
   "main": "index.js",
   "bin": {