@knowcode/doc-builder 1.4.1 → 1.4.3

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.3] - 2025-07-20
+
+### Fixed
+- Restored tooltip functionality by adding back the extractSummary function
+- Added data-tooltip attributes to navigation items showing document summaries
+- Removed unwanted Home link from sidebar breadcrumbs section
+- Navigation items now display helpful summaries on hover
+
+### Technical Details
+- extractSummary function extracts first 150 characters of meaningful content
+- Tooltips are properly escaped for HTML safety
+- Sidebar header simplified by removing redundant breadcrumb navigation
+
+## [1.4.2] - 2025-01-20
+
+### Fixed
+- Fixed excessive left padding on content area by removing JavaScript margin-left assignments
+- Content layout now properly uses flexbox spacing without manual margin adjustments
+- The JavaScript was adding inline `style="margin-left: 200px;"` which was causing the issue
+
 ## [1.4.1] - 2025-07-20
 
 ### Fixed

package/assets/css/notion-style.css

@@ -125,8 +125,8 @@
   /* Layout */
   --container-padding-mobile: 20px;
   --container-padding-desktop: 40px;
-  --header-height: 64px;
-  --breadcrumb-height: 40px;
+  --header-height: 40px;
+  --breadcrumb-height: 0px;
   --sidebar-width: 280px;
 }
 
@@ -169,6 +169,7 @@ h2 {
 h3 {
   font-size: var(--text-xl);
   margin-top: var(--space-8);
+  margin-bottom: var(--space-4);
 }
 
 h4 {
@@ -332,7 +333,42 @@ pre code {
   top: calc(var(--header-height) + var(--breadcrumb-height) + 3.5rem);
 }
 
-/* Sidebar header styles moved to main sidebar section */
+.sidebar-header {
+  padding: var(--space-4);
+  border-bottom: 1px solid var(--color-border-default);
+  margin-bottom: var(--space-4);
+}
+
+/* Sidebar Breadcrumbs */
+.sidebar-breadcrumbs {
+  margin-bottom: var(--space-3);
+}
+
+.sidebar-home-link {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-2) var(--space-3);
+  color: var(--color-text-secondary);
+  text-decoration: none;
+  border-radius: var(--radius-base);
+  font-size: 0.875rem;
+  font-weight: 500;
+  transition: all 0.2s;
+}
+
+.sidebar-home-link:hover {
+  background: var(--color-bg-secondary);
+  color: var(--color-text-primary);
+}
+
+.sidebar-home-link i {
+  font-size: 1rem;
+}
+
+.filter-box {
+  position: relative;
+}
 
 .filter-input {
   width: 100%;
@@ -493,6 +529,12 @@ pre code {
 .sidebar-header {
   padding: var(--space-3);
   border-bottom: 1px solid var(--color-border-default);
+  margin-bottom: var(--space-4);
+}
+
+/* Already defined above, but ensure consistency */
+.sidebar-breadcrumbs {
+  margin-bottom: var(--space-3);
 }
 
 .filter-box {
@@ -683,11 +725,21 @@ pre code {
 }
 
 /* Main Content */
-/* Removed duplicate .main-wrapper - using the one defined earlier */
+.main-wrapper {
+  display: flex;
+  padding-top: calc(var(--header-height) + var(--breadcrumb-height));
+  min-height: 100vh;
+  transition: padding-top var(--duration-normal);
+}
+
+/* Adjust layout when banner is visible */
+.main-wrapper.banner-visible {
+  padding-top: calc(var(--header-height) + var(--breadcrumb-height) + 3.5rem);
+}
 
 .content {
   flex: 1;
-  padding: var(--space-6) var(--space-8);
+  padding: 40px var(--space-8);
   overflow-y: auto;
   background: var(--color-bg-default);
 }
@@ -788,6 +840,7 @@ tr:hover {
   border: 1px solid var(--color-border-default);
   border-radius: var(--radius-lg);
   padding: var(--space-6);
+  margin-bottom: var(--space-4);
   box-shadow: var(--shadow-sm);
   transition: all var(--duration-normal) var(--easing-out);
 }
@@ -970,43 +1023,6 @@ tr:hover {
   cursor: pointer;
   color: var(--color-text-primary);
   padding: var(--space-2);
-  margin-left: var(--space-2);
-  transition: color var(--duration-fast);
-  z-index: 1001;
-}
-
-.menu-toggle:hover {
-  color: var(--color-accent-blue);
-}
-
-.menu-toggle.active i::before {
-  content: "\f00d"; /* fa-times icon */
-}
-
-/* Mobile Sidebar Overlay */
-.sidebar-overlay {
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background: var(--color-bg-overlay);
-  z-index: 998;
-  opacity: 0;
-  visibility: hidden;
-  transition: opacity var(--duration-normal), visibility var(--duration-normal);
-  display: none;
-}
-
-@media (max-width: 1024px) {
-  .sidebar-overlay {
-    display: block;
-  }
-}
-
-.sidebar-overlay.active {
-  opacity: 1;
-  visibility: visible;
 }
 
 /* Responsive Design */
@@ -1014,8 +1030,6 @@ tr:hover {
   .sidebar {
     transform: translateX(-100%);
     transition: transform var(--duration-normal) var(--easing-out);
-    z-index: 999;
-    box-shadow: 2px 0 10px rgba(0, 0, 0, 0.1);
   }
   
   .sidebar.open {
@@ -1027,6 +1041,7 @@ tr:hover {
   }
   
   .content {
+    margin-left: 0;
     padding: var(--space-6) var(--space-4);
   }
   
@@ -1434,6 +1449,7 @@ tr:hover {
   font-size: var(--text-lg);
   font-weight: var(--font-semibold);
   color: var(--color-text-primary);
+  margin-bottom: var(--space-4);
   padding-bottom: var(--space-2);
   border-bottom: 2px solid var(--color-divider);
 }
@@ -1806,9 +1822,11 @@ tr:hover {
 .auth-box p {
   color: var(--color-text-secondary);
   text-align: center;
+  margin-bottom: var(--space-4);
 }
 
 .form-group {
+  margin-bottom: var(--space-4);
 }
 
 .form-group label {

package/assets/js/main.js

@@ -511,30 +511,10 @@ function updateThemeIcon(theme) {
 // Mobile Menu Toggle
 const menuToggle = document.getElementById('menu-toggle');
 const sidebar = document.querySelector('.sidebar');
-const sidebarOverlay = document.querySelector('.sidebar-overlay');
 
 if (menuToggle) {
   menuToggle.addEventListener('click', () => {
     sidebar.classList.toggle('open');
-    sidebarOverlay.classList.toggle('active');
-    menuToggle.classList.toggle('active');
-    
-    // Prevent body scroll when menu is open
-    if (sidebar.classList.contains('open')) {
-      document.body.style.overflow = 'hidden';
-    } else {
-      document.body.style.overflow = '';
-    }
-  });
-}
-
-// Close sidebar when clicking overlay
-if (sidebarOverlay) {
-  sidebarOverlay.addEventListener('click', () => {
-    sidebar.classList.remove('open');
-    sidebarOverlay.classList.remove('active');
-    menuToggle.classList.remove('active');
-    document.body.style.overflow = '';
   });
 }
 
@@ -542,17 +522,14 @@ if (sidebarOverlay) {
 // Only close when clicking outside the sidebar or the close button
 document.addEventListener('click', (e) => {
   // Check if we're on mobile
-  if (window.innerWidth <= 1024) {
+  if (window.innerWidth <= 768) {
     const isClickInsideSidebar = sidebar && sidebar.contains(e.target);
     const isMenuToggle = e.target.closest('#menu-toggle');
-    const isOverlay = e.target.closest('.sidebar-overlay');
+    const isNavItem = e.target.closest('.nav-item, .nav-title');
     
-    // Close sidebar when clicking nav items on mobile
-    if (e.target.closest('.nav-item') && sidebar?.classList.contains('open')) {
+    // Close sidebar only if clicking outside AND not on menu toggle AND not on nav items
+    if (!isClickInsideSidebar && !isMenuToggle && !isNavItem && sidebar?.classList.contains('open')) {
       sidebar.classList.remove('open');
-      sidebarOverlay?.classList.remove('active');
-      menuToggle?.classList.remove('active');
-      document.body.style.overflow = '';
     }
   }
 });
@@ -689,9 +666,6 @@ document.addEventListener('keydown', (e) => {
   // Escape to close mobile menu
   if (e.key === 'Escape') {
     sidebar?.classList.remove('open');
-    sidebarOverlay?.classList.remove('active');
-    menuToggle?.classList.remove('active');
-    document.body.style.overflow = '';
   }
 });
 
@@ -730,7 +704,7 @@ function initSidebarResize() {
   const savedWidth = localStorage.getItem('sidebarWidth');
   if (savedWidth && savedWidth >= 200 && savedWidth <= 500) {
     sidebar.style.width = `${savedWidth}px`;
-    content.style.marginLeft = `${savedWidth}px`;
+    // Don't set margin-left - flexbox handles the layout
   }
   
   // Mouse down on resize handle
@@ -759,7 +733,7 @@ function initSidebarResize() {
     const constrainedWidth = Math.max(200, Math.min(500, width));
     
     sidebar.style.width = `${constrainedWidth}px`;
-    content.style.marginLeft = `${constrainedWidth}px`;
+    // Don't set margin-left - flexbox handles the layout
     
     e.preventDefault();
   }
@@ -801,7 +775,7 @@ function initSidebarResize() {
     const constrainedWidth = Math.max(200, Math.min(500, width));
     
     sidebar.style.width = `${constrainedWidth}px`;
-    content.style.marginLeft = `${constrainedWidth}px`;
+    // Don't set margin-left - flexbox handles the layout
     
     e.preventDefault();
   }
@@ -1085,7 +1059,6 @@ function exportToPDF() {
   const mainWrapper = document.querySelector('.main-wrapper');
   
   if (content) {
-    content.style.marginLeft = '0';
     content.style.padding = '20px';
     content.style.maxWidth = 'none';
   }
@@ -1200,7 +1173,6 @@ function exportToPDF() {
       
       // Restore content styles
       if (content) {
-        content.style.marginLeft = '';
         content.style.padding = '';
         content.style.maxWidth = '';
       }
@@ -1333,21 +1305,15 @@ function generateBreadcrumbs() {
 // Initialize tooltip positioning for navigation items
 function initTooltips() {
   const tooltipElements = document.querySelectorAll('[data-tooltip]');
-  console.log('[Tooltips] Found', tooltipElements.length, 'elements with tooltips');
   
   tooltipElements.forEach(element => {
     element.addEventListener('mouseenter', function(e) {
       const rect = element.getBoundingClientRect();
+      const tooltip = window.getComputedStyle(element, '::after');
       
       // Position the tooltip using CSS variables
       element.style.setProperty('--tooltip-left', `${rect.right + 10}px`);
       element.style.setProperty('--tooltip-top', `${rect.top + rect.height / 2}px`);
-      console.log('[Tooltip] Positioned at:', rect.right + 10, rect.top + rect.height / 2);
-    });
-    
-    element.addEventListener('mouseleave', function(e) {
-      element.style.removeProperty('--tooltip-left');
-      element.style.removeProperty('--tooltip-top');
     });
   });
 }

package/lib/core-builder.js

@@ -24,42 +24,34 @@ function escapeHtml(text) {
   return text.replace(/[&<>"']/g, m => map[m]);
 }
 
-// Extract summary from markdown content
-function extractSummary(content) {
-  // Look for ## Overview or ## Summary section
-  const overviewMatch = content.match(/##\s+(?:Overview|Summary)\s*\n([\s\S]*?)(?=\n##|$)/i);
-  if (overviewMatch) {
-    // Get first paragraph or up to 200 characters
-    const text = overviewMatch[1].trim();
-    const firstPara = text.split('\n\n')[0];
-    return firstPara.length > 200 ? firstPara.substring(0, 200) + '...' : firstPara;
-  }
+// Extract summary from markdown content for tooltips
+function extractSummary(content, maxLength = 150) {
+  // Remove front matter
+  content = content.replace(/^---[\s\S]*?---\n/, '');
   
-  // Fallback: get first paragraph after title
-  const lines = content.split('\n');
-  let foundContent = false;
-  let summary = '';
-  
-  for (const line of lines) {
-    // Skip title lines
-    if (line.startsWith('#')) continue;
-    // Skip metadata lines
-    if (line.includes('**Generated**:') || line.includes('**Status**:') || line.includes('**Verified**:')) continue;
-    // Skip empty lines until we find content
-    if (!foundContent && line.trim() === '') continue;
-    
-    if (line.trim()) {
-      foundContent = true;
-      summary += line + ' ';
-      if (summary.length > 200) break;
-    } else if (foundContent) {
-      // Found end of first paragraph
-      break;
-    }
+  // Remove headers
+  content = content.replace(/^#+\s+.+$/gm, '');
+  
+  // Remove code blocks
+  content = content.replace(/```[\s\S]*?```/g, '');
+  content = content.replace(/`[^`]+`/g, '');
+  
+  // Remove images and links
+  content = content.replace(/!\[[^\]]*\]\([^)]*\)/g, '');
+  content = content.replace(/\[[^\]]*\]\([^)]*\)/g, '');
+  
+  // Remove HTML tags
+  content = content.replace(/<[^>]+>/g, '');
+  
+  // Remove extra whitespace
+  content = content.trim().replace(/\s+/g, ' ');
+  
+  // Truncate if needed
+  if (content.length > maxLength) {
+    content = content.substring(0, maxLength).trim() + '...';
   }
   
-  summary = summary.trim();
-  return summary.length > 200 ? summary.substring(0, 200) + '...' : summary;
+  return content || 'No description available';
 }
 
 // Process markdown content
@@ -121,6 +113,7 @@ function generateHTML(title, content, navigation, currentPath = '', config = {})
     
     <!-- Styles -->
     <link rel="stylesheet" href="/css/notion-style.css">
+    <link rel="stylesheet" href="/css/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>">
@@ -178,9 +171,6 @@ function generateHTML(title, content, navigation, currentPath = '', config = {})
     
     <!-- Main Content -->
     <div class="main-wrapper">
-        <!-- Sidebar Overlay -->
-        <div class="sidebar-overlay"></div>
-        
         <!-- Sidebar -->
         <aside class="sidebar">
             <div class="sidebar-header">
@@ -232,7 +222,7 @@ const folderDescriptions = {
 };
 
 // Build navigation structure with rich functionality
-function buildNavigationStructure(files, currentFile, summaries = {}) {
+function buildNavigationStructure(files, currentFile) {
   const tree = { files: [], folders: {} };
   
   files.forEach(file => {
@@ -279,7 +269,7 @@ function buildNavigationStructure(files, currentFile, summaries = {}) {
   };
   
   // Helper function to render a section
-  const renderSection = (folderName, folderData, level = 0, parentPath = '', summaries = {}) => {
+  const renderSection = (folderName, folderData, level = 0, parentPath = '') => {
     const icons = {
       'root': 'fas fa-home',
       'product-roadmap': 'fas fa-road',
@@ -323,7 +313,7 @@ function buildNavigationStructure(files, currentFile, summaries = {}) {
     
     // Get folder description for tooltip
     const folderDescription = folderDescriptions[folderName] || '';
-    const tooltipAttr = folderDescription ? `data-tooltip="${escapeHtml(folderDescription)}" title="${escapeHtml(folderDescription)}"` : '';
+    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);
@@ -355,13 +345,10 @@ function buildNavigationStructure(files, currentFile, summaries = {}) {
       }
       
       const linkPath = '/' + file.urlPath;
-      
-      // Get summary for tooltip
-      const summary = summaries[file.urlPath] || '';
-      const tooltipAttr = summary ? `data-tooltip="${escapeHtml(summary)}"` : '';
+      const tooltip = file.summary ? ` data-tooltip="${escapeHtml(file.summary)}"` : '';
       
       html += `
-        <a href="${linkPath}" class="nav-item${isActive}" ${tooltipAttr}><i class="fas fa-file-alt"></i> ${title}</a>`;
+        <a href="${linkPath}" class="nav-item${isActive}"${tooltip}><i class="fas fa-file-alt"></i> ${title}</a>`;
     });
     
     html += `</div></div>`;
@@ -372,7 +359,7 @@ function buildNavigationStructure(files, currentFile, summaries = {}) {
       .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, summaries);
+        html += renderSection(subFolder, folderData.folders[subFolder], level + 1, currentPath);
       });
     
     return html;
@@ -383,14 +370,14 @@ function buildNavigationStructure(files, currentFile, summaries = {}) {
   
   if (!hasFolders) {
     // Generate simple flat navigation for all files in root
-    return renderSection('root', { files: tree.files, folders: {} }, 0, '', summaries);
+    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, '', summaries);
+      nav += renderSection('root', { files: tree.files, folders: {} }, 0);
     }
     
     // Add other top-level folders in logical order
@@ -413,7 +400,7 @@ function buildNavigationStructure(files, currentFile, summaries = {}) {
     
     folderOrder.forEach(folderName => {
       if (tree.folders[folderName]) {
-        nav += renderSection(folderName, tree.folders[folderName], 1, '', summaries);
+        nav += renderSection(folderName, tree.folders[folderName], 1);
         delete tree.folders[folderName]; // Remove so we don't render it again
       }
     });
@@ -422,7 +409,7 @@ function buildNavigationStructure(files, currentFile, summaries = {}) {
     Object.keys(tree.folders)
       .sort()
       .forEach(folderName => {
-        nav += renderSection(folderName, tree.folders[folderName], 1, '', summaries);
+        nav += renderSection(folderName, tree.folders[folderName], 1);
       });
     
     return nav;
@@ -430,7 +417,7 @@ function buildNavigationStructure(files, currentFile, summaries = {}) {
 }
 
 // Process single markdown file
-async function processMarkdownFile(filePath, outputPath, allFiles, config, summaries = {}) {
+async function processMarkdownFile(filePath, outputPath, allFiles, config) {
   const content = await fs.readFile(filePath, 'utf-8');
   const fileName = path.basename(filePath, '.md');
   const relativePath = path.relative(config.docsDir, filePath);
@@ -440,11 +427,14 @@ async function processMarkdownFile(filePath, outputPath, allFiles, config, summa
   const titleMatch = content.match(/^#\s+(.+)$/m);
   const title = titleMatch ? titleMatch[1] : fileName;
   
+  // Extract summary for tooltip
+  const summary = extractSummary(content);
+  
   // Process content
   const htmlContent = processMarkdownContent(content);
   
   // Build navigation
-  const navigation = buildNavigationStructure(allFiles, urlPath, summaries);
+  const navigation = buildNavigationStructure(allFiles, urlPath);
   
   // Generate full HTML
   const html = generateHTML(title, htmlContent, navigation, urlPath, config);
@@ -453,7 +443,7 @@ async function processMarkdownFile(filePath, outputPath, allFiles, config, summa
   await fs.ensureDir(path.dirname(outputPath));
   await fs.writeFile(outputPath, html);
   
-  return { title, urlPath };
+  return { title, urlPath, summary };
 }
 
 // Get all markdown files
@@ -475,11 +465,16 @@ async function getAllMarkdownFiles(dir, baseDir = dir) {
         .replace(/[-_]/g, ' ')
         .replace(/\b\w/g, l => l.toUpperCase());
       
+      // Read file to extract summary
+      const content = await fs.readFile(fullPath, 'utf-8');
+      const summary = extractSummary(content);
+      
       files.push({
         path: fullPath,
         relativePath,
         urlPath,
-        displayName
+        displayName,
+        summary
       });
     }
   }
@@ -512,21 +507,10 @@ async function buildDocumentation(config) {
     });
   }
   
-  // First pass: collect summaries
-  console.log(chalk.blue('📊 Extracting summaries...'));
-  const summaries = {};
-  for (const file of files) {
-    const content = await fs.readFile(file.path, 'utf-8');
-    const summary = extractSummary(content);
-    if (summary) {
-      summaries[file.urlPath] = summary;
-    }
-  }
-  
   console.log(chalk.blue('📝 Processing files...'));
   for (const file of files) {
     const outputPath = path.join(outputDir, file.urlPath);
-    await processMarkdownFile(file.path, outputPath, files, config, summaries);
+    await processMarkdownFile(file.path, outputPath, files, config);
     console.log(chalk.green(`✅ Generated: ${outputPath}`));
   }
   
@@ -873,6 +857,7 @@ async function createDefaultIndexPage(outputDir, config, version) {
     <title>Welcome to ${siteName}</title>
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
     <link rel="stylesheet" href="/css/notion-style.css">
+    <link rel="stylesheet" href="/css/style.css">
     <style>
       .welcome-container {
         max-width: 800px;

package/package/CACHE-BUSTING-GUIDE.md

@@ -0,0 +1,82 @@
+# Cache Busting Guide for @knowcode/doc-builder
+
+If you're not seeing updates after upgrading to a new version, it's likely due to caching. Follow these steps:
+
+## 1. Clean Everything Locally
+
+```bash
+# Remove old build artifacts
+rm -rf html/
+
+# Clear npm cache
+npm cache clean --force
+
+# Remove node_modules and reinstall
+rm -rf node_modules
+npm install
+
+# Make sure you have the latest version
+npm install @knowcode/doc-builder@latest
+```
+
+## 2. Rebuild with Fresh Files
+
+```bash
+# Build fresh documentation
+npx @knowcode/doc-builder build
+```
+
+## 3. Deploy with Force Flag
+
+```bash
+# Force Vercel to ignore cache
+vercel --prod --force
+```
+
+## 4. Clear Browser Cache
+
+- **Chrome/Edge**: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
+- **Firefox**: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
+- **Safari**: Cmd+Option+R
+- Or use Incognito/Private browsing mode
+
+## 5. Clear Vercel/CDN Cache (if applicable)
+
+If using Vercel:
+1. Go to your project dashboard
+2. Settings → Functions → Purge Cache
+3. Or redeploy with a different domain temporarily
+
+## 6. Add Cache Busting to Your Build
+
+Edit your `doc-builder.config.js` to add version query strings:
+
+```javascript
+module.exports = {
+  // ... other config
+  cacheBust: true, // This will add ?v=timestamp to CSS/JS files
+};
+```
+
+## Common Issues
+
+- **"I updated but nothing changed"** - It's cache. Follow all steps above.
+- **"Tooltips still don't work"** - Clear browser cache and check console for errors
+- **"Spacing is still wrong"** - The CSS is cached. Hard refresh the page.
+
+## Verify You Have The Right Version
+
+Check the version in your package.json:
+```bash
+npm list @knowcode/doc-builder
+```
+
+Should show: `@knowcode/doc-builder@1.3.13` or higher.
+
+## Still Not Working?
+
+1. Open browser DevTools
+2. Go to Network tab
+3. Check "Disable cache" checkbox
+4. Refresh the page
+5. Look at the CSS/JS files being loaded - they should not show "(from cache)"