@knowcode/doc-builder 1.4.2 → 1.4.3

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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

package/lib/core-builder.js

@@ -24,6 +24,36 @@ function escapeHtml(text) {
   return text.replace(/[&<>"']/g, m => map[m]);
 }
 
+// Extract summary from markdown content for tooltips
+function extractSummary(content, maxLength = 150) {
+  // Remove front matter
+  content = content.replace(/^---[\s\S]*?---\n/, '');
+  
+  // 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() + '...';
+  }
+  
+  return content || 'No description available';
+}
+
 // Process markdown content
 function processMarkdownContent(content) {
   // Convert mermaid code blocks to mermaid divs with titles
@@ -144,12 +174,6 @@ function generateHTML(title, content, navigation, currentPath = '', config = {})
         <!-- Sidebar -->
         <aside class="sidebar">
             <div class="sidebar-header">
-                <div class="sidebar-breadcrumbs">
-                    <a href="/index.html" class="sidebar-home-link">
-                        <i class="fas fa-home"></i>
-                        <span>Home</span>
-                    </a>
-                </div>
                 <div class="filter-box">
                     <input type="text" placeholder="Filter items..." class="filter-input" id="nav-filter">
                     <i class="fas fa-search filter-icon"></i>
@@ -321,9 +345,10 @@ function buildNavigationStructure(files, currentFile) {
       }
       
       const linkPath = '/' + file.urlPath;
+      const tooltip = file.summary ? ` data-tooltip="${escapeHtml(file.summary)}"` : '';
       
       html += `
-        <a href="${linkPath}" class="nav-item${isActive}"><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>`;
@@ -402,6 +427,9 @@ async function processMarkdownFile(filePath, outputPath, allFiles, config) {
   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);
   
@@ -415,7 +443,7 @@ async function processMarkdownFile(filePath, outputPath, allFiles, config) {
   await fs.ensureDir(path.dirname(outputPath));
   await fs.writeFile(outputPath, html);
   
-  return { title, urlPath };
+  return { title, urlPath, summary };
 }
 
 // Get all markdown files
@@ -437,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
       });
     }
   }

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)"