@knowcode/doc-builder 1.1.12 → 1.2.1

package/lib/core-builder.js

@@ -123,18 +123,43 @@ function generateHTML(title, content, navigation, currentPath = '', config = {})
         </div>
     </header>
     
-    <div class="container">
-        <!-- Navigation -->
-        <nav id="navigation" class="navigation">
-            <div class="nav-header">
-                <h3>${siteName}</h3>
+    <!-- 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>
-            ${navigation}
-        </nav>
+            <nav class="navigation">
+                ${navigation}
+            </nav>
+            <div class="resize-handle"></div>
+        </aside>
         
-        <!-- Main Content -->
+        <!-- Content Area -->
         <main class="content">
-            ${content}
+            <div class="content-inner">
+                ${content}
+            </div>
         </main>
     </div>
     
@@ -145,7 +170,28 @@ function generateHTML(title, content, navigation, currentPath = '', config = {})
 </html>`;
 }
 
-// Build navigation structure
+// Define folder descriptions for tooltips
+const folderDescriptions = {
+  'product-roadmap': 'Strategic vision, timeline, and feature planning',
+  'product-requirements': 'Detailed product specifications, requirements documents, and feature definitions',
+  'architecture': 'System design, data flows, and technical infrastructure documentation',
+  'system-analysis': 'Comprehensive system analysis, functional requirements, and cross-component documentation',
+  'bubble': 'Core application platform - business logic, UI/UX, and user workflows',
+  'quickbase': 'Database schema, data management, and backend operations',
+  'activecampaign': 'Marketing automation integration and lead management system',
+  'juno-signer': 'Document signing service for digital signatures and PDF generation',
+  'juno-api-deprecated': 'Legacy API documentation (deprecated, for reference only)',
+  'postman': 'API testing tools, collections, and test automation',
+  'mcp': 'Model Context Protocol integration and configuration',
+  'team': 'Team structure, roles, and responsibilities',
+  'thought-leadership': 'Strategic insights and industry perspectives',
+  'middleware': 'Integration layers and data transformation services',
+  'paths': 'User journey flows and process workflows',
+  'testing': 'Test strategies, scenarios, and quality assurance processes',
+  'juno-api': 'API documentation and integration guides'
+};
+
+// Build navigation structure with rich functionality
 function buildNavigationStructure(files, currentFile) {
   const tree = { files: [], folders: {} };
   
@@ -166,71 +212,176 @@ function buildNavigationStructure(files, currentFile) {
     current.files.push(file);
   });
   
-  // Check if this is a flat structure
-  const hasFolders = Object.keys(tree.folders).length > 0;
+  // Helper function to check if a node has active child
+  const checkActiveChild = (node, currentFile) => {
+    // Check files
+    if (node.files.some(f => f.urlPath === currentFile)) return true;
+    
+    // Check folders recursively
+    return Object.values(node.folders).some(folder => checkActiveChild(folder, currentFile));
+  };
   
-  if (!hasFolders) {
-    // Generate simple flat navigation that matches what JavaScript expects
-    let html = '<div class="nav-section">';
-    html += '<div class="nav-content">';
-    
-    tree.files.forEach(file => {
-      const isActive = file.urlPath === currentFile;
-      const href = file.urlPath.replace(/\\/g, '/');
-      html += `<div class="nav-item ${isActive ? 'active' : ''}">
-        <a href="${href}" class="nav-link ${isActive ? 'active' : ''}">
-          <span class="nav-text">${file.displayName}</span>
+  // Helper function to generate file title
+  const generateFileTitle = (file, parentDisplayName, level) => {
+    let title = file.displayName;
+    
+    if (file.displayName === 'README') {
+      return level === 0 ? 'Overview' : `${parentDisplayName} Overview`;
+    }
+    
+    // Clean up title by removing common prefixes and improving formatting
+    title = title
+      .replace(/^(bubble|system|quickbase|middleware|product-roadmap)-?/, '')
+      .replace(/-/g, ' ')
+      .replace(/\b\w/g, l => l.toUpperCase());
+    
+    return title;
+  };
+  
+  // Helper function to render a section
+  const renderSection = (folderName, folderData, level = 0, parentPath = '') => {
+    const icons = {
+      'root': 'fas fa-home',
+      'product-roadmap': 'fas fa-road',
+      'product-requirements': 'fas fa-clipboard-list',
+      'architecture': 'fas fa-sitemap',
+      'system-analysis': 'fas fa-chart-line',
+      'system': 'fas fa-cogs',
+      'bubble': 'fas fa-circle',
+      'quickbase': 'fas fa-database',
+      'activecampaign': 'fas fa-envelope',
+      'juno-signer': 'fas fa-signature',
+      'juno-api-deprecated': 'fas fa-archive',
+      'postman': 'fas fa-flask',
+      'mcp': 'fas fa-puzzle-piece',
+      'team': 'fas fa-users',
+      'thought-leadership': 'fas fa-lightbulb',
+      'middleware': 'fas fa-layer-group',
+      'paths': 'fas fa-route',
+      'testing': 'fas fa-vial',
+      'juno-api': 'fas fa-plug',
+      'documentation-tool': 'fas fa-tools'
+    };
+    
+    const displayName = folderName === 'root' ? 'Documentation' : 
+                       folderName.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
+    const icon = icons[folderName] || 'fas fa-folder';
+    
+    if (!folderData.files.length && !Object.keys(folderData.folders).length) {
+      return '';
+    }
+    
+    // Include parent path in section ID to make it unique
+    const pathParts = parentPath ? [parentPath, folderName].join('-') : folderName;
+    const sectionId = `nav-${pathParts}-${level}`;
+    const isCollapsible = level > 0 || folderName !== 'root';
+    const collapseIcon = isCollapsible ? '<i class="fas fa-chevron-right collapse-icon"></i>' : '';
+    
+    // Check if this folder has a README.md file to link to
+    const readmeFile = folderData.files.find(f => f.displayName === 'README');
+    const folderLink = readmeFile ? `href="/${readmeFile.urlPath}"` : 'href="#"';
+    
+    // Get folder description for tooltip
+    const folderDescription = folderDescriptions[folderName] || '';
+    const tooltipAttr = folderDescription ? `data-tooltip="${escapeHtml(folderDescription)}"` : '';
+    
+    // Start all sections collapsed by default (JavaScript will expand sections containing active items)
+    const hasActiveChild = checkActiveChild(folderData, currentFile);
+    
+    let html = `
+      <div class="nav-section" data-level="${level}">
+        <a class="nav-title${isCollapsible ? ' collapsible' : ''}${hasActiveChild ? ' expanded' : ''}" ${folderLink} ${isCollapsible ? `data-target="${sectionId}"` : ''} ${tooltipAttr}>
+          ${collapseIcon}<i class="${icon}"></i> ${displayName}
         </a>
-      </div>`;
+        <div class="nav-content${isCollapsible ? (hasActiveChild ? '' : ' collapsed') : ''}" ${isCollapsible ? `id="${sectionId}"` : ''}>`;
+    
+    // Sort and render files
+    const sortedFiles = [...folderData.files].sort((a, b) => {
+      if (a.displayName === 'README') return -1;
+      if (b.displayName === 'README') return 1;
+      return a.displayName.localeCompare(b.displayName);
     });
     
-    html += '</div></div>';
-    return html;
-  } else {
-    // Generate collapsible navigation for folder structures
-    const generateNavHTML = (node, path = '', level = 0) => {
-      let html = '';
+    sortedFiles.forEach(file => {
+      const title = generateFileTitle(file, displayName, level);
       
-      // Add folders as sections
-      Object.entries(node.folders).forEach(([folderName, folderNode]) => {
-        const folderPath = path ? `${path}/${folderName}` : folderName;
-        const hasActiveChild = checkActiveChild(folderNode, currentFile);
-        const sectionId = `nav-${folderPath.replace(/\//g, '-')}`;
-        
-        html += `<div class="nav-section ${hasActiveChild ? 'expanded' : ''}">
-          <div class="nav-title collapsible ${hasActiveChild ? 'expanded' : ''}" data-target="${sectionId}">
-            <i class="fas fa-chevron-${hasActiveChild ? 'down' : 'right'}"></i>
-            <span class="nav-text">${folderName}</span>
-          </div>
-          <div class="nav-content ${hasActiveChild ? '' : 'collapsed'}" id="${sectionId}">
-            ${generateNavHTML(folderNode, folderPath, level + 1)}
-          </div>
-        </div>`;
-      });
+      // Check if this file is active
+      let isActive = '';
+      if (currentFile === file.urlPath) {
+        isActive = ' active';
+      } else if (currentFile === 'index.html' && file.displayName === 'README' && folderName === 'root') {
+        // Mark root README as active when viewing index.html
+        isActive = ' active';
+      }
       
-      // Add files
-      node.files.forEach(file => {
-        const isActive = file.urlPath === currentFile;
-        const href = file.urlPath.replace(/\\/g, '/');
-        html += `<div class="nav-item ${isActive ? 'active' : ''}">
-          <a href="${href}" class="nav-link ${isActive ? 'active' : ''}">
-            <span class="nav-text">${file.displayName}</span>
-          </a>
-        </div>`;
-      });
+      const linkPath = '/' + file.urlPath;
       
-      return html;
-    };
+      html += `
+        <a href="${linkPath}" class="nav-item${isActive}"><i class="fas fa-file-alt"></i> ${title}</a>`;
+    });
     
-    const checkActiveChild = (node, currentFile) => {
-      // Check files
-      if (node.files.some(f => f.urlPath === currentFile)) return true;
-      
-      // Check folders recursively
-      return Object.values(node.folders).some(folder => checkActiveChild(folder, currentFile));
-    };
+    html += `</div></div>`;
+    
+    // Render subfolders AFTER closing the parent section
+    Object.keys(folderData.folders)
+      .sort()
+      .forEach(subFolder => {
+        // Build the path for the subfolder including current folder
+        const currentPath = parentPath ? `${parentPath}-${folderName}` : folderName;
+        html += renderSection(subFolder, folderData.folders[subFolder], level + 1, currentPath);
+      });
+    
+    return html;
+  };
+  
+  // Check if this is a flat structure
+  const hasFolders = Object.keys(tree.folders).length > 0;
+  
+  if (!hasFolders) {
+    // Generate simple flat navigation for all files in root
+    return renderSection('root', { files: tree.files, folders: {} }, 0);
+  } else {
+    // Generate hierarchical navigation
+    let nav = '';
+    
+    // Render root files first
+    if (tree.files.length > 0) {
+      nav += renderSection('root', { files: tree.files, folders: {} }, 0);
+    }
+    
+    // Add other top-level folders in logical order
+    const folderOrder = [
+      'product-roadmap',
+      'product-requirements', 
+      'architecture',
+      'system-analysis',
+      'bubble',
+      'quickbase',
+      'activecampaign',
+      'juno-signer',
+      'juno-api-deprecated',
+      'postman',
+      'mcp',
+      'team',
+      'thought-leadership',
+      'documentation-tool'
+    ];
+    
+    folderOrder.forEach(folderName => {
+      if (tree.folders[folderName]) {
+        nav += renderSection(folderName, tree.folders[folderName], 1);
+        delete tree.folders[folderName]; // Remove so we don't render it again
+      }
+    });
+    
+    // Render any remaining folders not in the predefined order
+    Object.keys(tree.folders)
+      .sort()
+      .forEach(folderName => {
+        nav += renderSection(folderName, tree.folders[folderName], 1);
+      });
     
-    return generateNavHTML(tree);
+    return nav;
   }
 }
 
@@ -297,9 +448,13 @@ async function buildDocumentation(config) {
   const docsDir = path.join(process.cwd(), config.docsDir);
   const outputDir = path.join(process.cwd(), config.outputDir);
   
+  // Check and create placeholder README.md if missing
+  console.log(chalk.blue('📋 Checking documentation structure...'));
+  const readmeGenerated = await createPlaceholderReadme(docsDir, config);
+  
   console.log(chalk.blue('📄 Scanning for markdown files...'));
   const files = await getAllMarkdownFiles(docsDir);
-  console.log(chalk.green(`✅ Found ${files.length} markdown files`));
+  console.log(chalk.green(`✅ Found ${files.length} markdown files${readmeGenerated ? ' (including auto-generated README)' : ''}`));
   
   console.log(chalk.blue('📝 Processing files...'));
   for (const file of files) {
@@ -338,6 +493,99 @@ async function buildDocumentation(config) {
   console.log(chalk.green('✅ Documentation build complete!'));
 }
 
+// Create placeholder README.md if missing
+async function createPlaceholderReadme(docsDir, config) {
+  const readmePath = path.join(docsDir, 'README.md');
+  
+  // Check if README.md already exists
+  if (fs.existsSync(readmePath)) {
+    return false; // README already exists, no need to create
+  }
+  
+  const siteName = config.siteName || 'Documentation';
+  const currentDate = new Date().toISOString().split('T')[0];
+  
+  const placeholderContent = `# Welcome to ${siteName}
+
+**Generated**: ${currentDate} UTC
+**Status**: Placeholder - Ready for customization
+**Verified**: ❓ (Auto-generated content)
+
+## Overview
+
+This documentation site was built with @knowcode/doc-builder. This is an auto-generated placeholder to help you get started.
+
+## Getting Started
+
+1. **Replace this file**: Edit \`docs/README.md\` with your project's actual documentation
+2. **Add content**: Create additional markdown files in the \`docs/\` directory
+3. **Organize with folders**: Use subfolders to structure your documentation
+4. **Rebuild**: Run \`npx @knowcode/doc-builder build\` to regenerate the site
+
+## Documentation Structure
+
+Your documentation can include:
+
+- **Overview**: Main project description (this file)
+- **Guides**: Step-by-step tutorials
+- **API Reference**: Technical documentation
+- **Examples**: Code samples and usage
+- **Architecture**: System design and technical details
+
+## Next Steps
+
+1. Edit this README.md file with your project information
+2. Create additional markdown files for your content
+3. Organize files into logical folders
+4. Use Mermaid diagrams for visual explanations
+5. Deploy with \`npx @knowcode/doc-builder deploy\`
+
+## Documentation Standards
+
+This project follows structured documentation conventions:
+
+### File Organization
+- Use descriptive filenames with hyphens (e.g., \`user-guide.md\`)
+- Organize related content in folders
+- Include a README.md in each major folder
+
+### Content Format
+- Start each document with metadata (Generated date, Status, Verified status)
+- Use clear headings and consistent structure
+- Include diagrams where helpful to explain concepts
+- Mark information as verified (✅) or speculated (❓)
+
+### Mermaid Diagrams
+Include visual diagrams to explain complex concepts:
+
+\`\`\`mermaid
+graph TD
+    A[Start Documentation] --> B{Have Content?}
+    B -->|Yes| C[Edit README.md]
+    B -->|No| D[Create Content Files]
+    C --> E[Build & Deploy]
+    D --> E
+    E --> F[Share Documentation]
+\`\`\`
+
+## Support
+
+For help with @knowcode/doc-builder:
+- Check the documentation at your package source
+- Use \`npx @knowcode/doc-builder --help\` for CLI options
+- Review the generated configuration guide if available
+`;
+
+  try {
+    await fs.writeFile(readmePath, placeholderContent);
+    console.log(chalk.yellow('📄 Auto-generated placeholder README.md - please customize it!'));
+    return true; // Successfully created placeholder
+  } catch (error) {
+    console.warn(chalk.yellow(`Warning: Could not create placeholder README.md: ${error.message}`));
+    return false;
+  }
+}
+
 // Create login/logout pages
 async function createAuthPages(outputDir, config) {
   // Login page
@@ -419,5 +667,6 @@ async function createAuthPages(outputDir, config) {
 module.exports = {
   buildDocumentation,
   processMarkdownContent,
-  generateHTML
+  generateHTML,
+  createPlaceholderReadme
 };

package/lib/deploy.js

@@ -365,72 +365,29 @@ async function prepareDeployment(config) {
       fs.writeFileSync(indexPath, redirectHtml);
       console.log(chalk.green('✅ Created index.html redirect to README.html'));
     } else {
-      // If no README.html, create a basic index listing all HTML files
-      const htmlFiles = fs.readdirSync(outputDir)
-        .filter(file => file.endsWith('.html') && file !== 'index.html')
-        .sort();
-      
-      if (htmlFiles.length > 0) {
-        const indexHtml = `<!DOCTYPE html>
+      // If no README.html, create a simple redirect to home
+      // This should rarely happen since build process now auto-generates README.md
+      const simpleIndex = `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Documentation</title>
-  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0-beta3/css/all.min.css">
+  <meta http-equiv="refresh" content="0; url=./">
+  <title>${config.siteName || 'Documentation'}</title>
   <link rel="stylesheet" href="/css/style.css">
   <link rel="stylesheet" href="/css/notion-style.css">
 </head>
 <body>
-  <div class="navigation">
-    <div class="nav-header">
-      <h2>${config.siteName || 'Documentation'}</h2>
-    </div>
-    <nav>
-      <ul>
-        ${htmlFiles.map(file => {
-          const name = file.replace('.html', '').replace(/-/g, ' ');
-          const capitalizedName = name.split(' ').map(word => 
-            word.charAt(0).toUpperCase() + word.slice(1)
-          ).join(' ');
-          return `<li><a href="${file}"><i class="fas fa-file"></i> ${capitalizedName}</a></li>`;
-        }).join('\n        ')}
-      </ul>
-    </nav>
-  </div>
-  <div class="content">
-    <div class="header">
-      <h1 style="text-align: center; margin: 50px 0;">📚 Documentation</h1>
-    </div>
-    <div class="main-content">
-      <div class="doc-grid" style="display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 20px; padding: 20px;">
-        ${htmlFiles.map(file => {
-          const name = file.replace('.html', '').replace(/-/g, ' ');
-          const capitalizedName = name.split(' ').map(word => 
-            word.charAt(0).toUpperCase() + word.slice(1)
-          ).join(' ');
-          return `
-        <a href="${file}" class="doc-card" style="display: block; padding: 20px; border: 1px solid #e1e4e8; border-radius: 8px; text-decoration: none; color: inherit; transition: all 0.2s;">
-          <h3 style="margin: 0 0 10px 0; color: #0366d6;"><i class="fas fa-file-alt"></i> ${capitalizedName}</h3>
-          <p style="margin: 0; color: #586069; font-size: 14px;">Click to view this documentation</p>
-        </a>`;
-        }).join('')}
-      </div>
-    </div>
+  <div style="text-align: center; margin-top: 50px; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;">
+    <h1>📚 ${config.siteName || 'Documentation'}</h1>
+    <p>Loading documentation...</p>
+    <p><a href="./" style="color: #0366d6;">Click here if not redirected automatically</a></p>
   </div>
-  <script src="/js/main.js"></script>
-  <style>
-    .doc-card:hover {
-      box-shadow: 0 4px 12px rgba(0,0,0,0.1);
-      transform: translateY(-2px);
-    }
-  </style>
 </body>
 </html>`;
-        fs.writeFileSync(indexPath, indexHtml);
-        console.log(chalk.green('✅ Created index.html with file listing'));
-        console.log(chalk.yellow('📌 Remember to rebuild before deploying to see styling!'));
-      }
+      fs.writeFileSync(indexPath, simpleIndex);
+      console.log(chalk.green('✅ Created index.html redirect'));
+      console.log(chalk.yellow('📌 Note: Consider running build to ensure README.md exists'));
     }
   }
 }

package/package.json

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

package/temp-test/docs/README.md

@@ -0,0 +1,69 @@
+# Welcome to Documentation
+
+**Generated**: 2025-07-19 UTC
+**Status**: Placeholder - Ready for customization
+**Verified**: ❓ (Auto-generated content)
+
+## Overview
+
+This documentation site was built with @knowcode/doc-builder. This is an auto-generated placeholder to help you get started.
+
+## Getting Started
+
+1. **Replace this file**: Edit `docs/README.md` with your project's actual documentation
+2. **Add content**: Create additional markdown files in the `docs/` directory
+3. **Organize with folders**: Use subfolders to structure your documentation
+4. **Rebuild**: Run `npx @knowcode/doc-builder build` to regenerate the site
+
+## Documentation Structure
+
+Your documentation can include:
+
+- **Overview**: Main project description (this file)
+- **Guides**: Step-by-step tutorials
+- **API Reference**: Technical documentation
+- **Examples**: Code samples and usage
+- **Architecture**: System design and technical details
+
+## Next Steps
+
+1. Edit this README.md file with your project information
+2. Create additional markdown files for your content
+3. Organize files into logical folders
+4. Use Mermaid diagrams for visual explanations
+5. Deploy with `npx @knowcode/doc-builder deploy`
+
+## Documentation Standards
+
+This project follows structured documentation conventions:
+
+### File Organization
+- Use descriptive filenames with hyphens (e.g., `user-guide.md`)
+- Organize related content in folders
+- Include a README.md in each major folder
+
+### Content Format
+- Start each document with metadata (Generated date, Status, Verified status)
+- Use clear headings and consistent structure
+- Include diagrams where helpful to explain concepts
+- Mark information as verified (✅) or speculated (❓)
+
+### Mermaid Diagrams
+Include visual diagrams to explain complex concepts:
+
+```mermaid
+graph TD
+    A[Start Documentation] --> B{Have Content?}
+    B -->|Yes| C[Edit README.md]
+    B -->|No| D[Create Content Files]
+    C --> E[Build & Deploy]
+    D --> E
+    E --> F[Share Documentation]
+```
+
+## Support
+
+For help with @knowcode/doc-builder:
+- Check the documentation at your package source
+- Use `npx @knowcode/doc-builder --help` for CLI options
+- Review the generated configuration guide if available

package/temp-test/docs/test-file.md

@@ -0,0 +1 @@
+# Test File