@knowcode/doc-builder 1.9.26 → 1.9.28

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.9.26] - 2025-08-10
+
+### Added
+- **Non-Printable Character Handling** - Automatically detects and skips files with non-printable ASCII characters (0x00-0x1F, 0x7F-0x9F) in their names
+- **Safe File Processing** - Prevents YAML parsing errors and build failures caused by malformed filenames
+- **Clear User Feedback** - Displays warning messages with sanitized filenames when problematic files are encountered
+- **Cross-Platform Compatibility** - Handles files with special characters from different operating systems
+
+### Fixed
+- **Build Failures** - Resolved "stream contains non-printable characters" YAML parsing errors during deployment
+- **File Scanning Issues** - Fixed crashes when encountering files with control characters or corrupted metadata
+- **Deployment Errors** - Eliminated deployment failures caused by problematic filenames in source directories
+
+### Technical
+- Added `hasNonPrintableChars()` function to detect problematic filenames
+- Added `sanitizeFilename()` function for safe display of problematic names
+- Updated all file scanning functions (`getAllMarkdownFiles`, `getAllAttachmentFiles`, `findHtmlFiles`)
+- Enhanced `fs.readdir` and `fs.readdirSync` operations with safety checks
+
 ## [1.9.18] - 2025-08-02
 
 ### Added

package/README.md

@@ -310,6 +310,23 @@ doc-builder automatically copies attachment files (Excel, PDF, images, etc.) to
 
 To disable attachment copying, use the `--no-attachments` flag with build or deploy commands.
 
+### 🛡️ File Safety & Non-Printable Character Handling
+
+doc-builder v1.9.26+ automatically handles files with non-printable characters in their names to prevent build failures:
+
+- **Automatic Detection**: Files with non-printable ASCII characters (0x00-0x1F, 0x7F-0x9F) are automatically detected
+- **Safe Processing**: Problematic files are skipped during scanning with a warning message
+- **Clear Feedback**: You'll see messages like: `⚠️ Skipping file with non-printable characters: [sanitized name]`
+- **Prevents Errors**: Eliminates YAML parsing errors and build failures caused by malformed filenames
+
+**Common scenarios this fixes**:
+- Files copied from certain operating systems with special characters
+- Documents exported from applications that add invisible control characters
+- Files with corruption in their metadata
+- Cross-platform compatibility issues
+
+This ensures your documentation builds successfully even when your source directory contains files with problematic names.
+
 ## 📋 Commands Overview
 
 <table>

package/assets/css/notion-style.css

@@ -534,6 +534,12 @@ pre code {
   overflow: hidden;
 }
 
+/* Static build main wrapper - adjust for no header and smaller breadcrumb */
+.breadcrumbs-static ~ .main-wrapper {
+  height: calc(100vh - 28px);
+  margin-top: 28px;
+}
+
 .main-wrapper.banner-visible {
   height: calc(100vh - var(--header-height) - var(--breadcrumb-height) - 3.5rem);
   margin-top: calc(var(--header-height) + var(--breadcrumb-height) + 3.5rem);
@@ -990,6 +996,76 @@ tr:hover {
   gap: var(--space-2);
 }
 
+/* Static build breadcrumbs - no header so top is 0 */
+.breadcrumbs-static {
+  top: 0 !important;
+  height: auto !important;
+  min-height: 28px !important;
+  padding: 0.15rem var(--space-6) !important;
+}
+
+/* Breadcrumbs content wrapper for static builds */
+.breadcrumbs-content {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+}
+
+.breadcrumbs-left {
+  display: flex;
+  align-items: center;
+  gap: 0;
+}
+
+.breadcrumbs-right {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+/* Timestamp in breadcrumbs */
+.breadcrumb-date {
+  color: var(--color-text-tertiary);
+  font-size: var(--text-xs);
+  white-space: nowrap;
+}
+
+/* PDF button in breadcrumbs */
+.breadcrumb-pdf-btn {
+  background: none;
+  border: none;
+  color: var(--color-text-secondary);
+  cursor: pointer;
+  padding: var(--space-1) var(--space-2);
+  border-radius: var(--radius-md);
+  transition: all 0.2s;
+  font-size: 1rem;
+}
+
+.breadcrumb-pdf-btn:hover {
+  background: var(--color-bg-tertiary);
+  color: var(--color-text-primary);
+}
+
+/* Minimal breadcrumbs for homepage - even more compact */
+.breadcrumbs-minimal.breadcrumbs-static {
+  height: auto !important;
+  min-height: 24px !important;
+  padding: 0.1rem var(--space-6) !important;
+}
+
+/* Homepage breadcrumbs content - right-aligned only */
+.breadcrumbs-homepage {
+  justify-content: flex-end !important;
+}
+
+/* Adjust main wrapper for minimal breadcrumbs */
+.breadcrumbs-minimal.breadcrumbs-static ~ .main-wrapper {
+  height: calc(100vh - 24px);
+  margin-top: 24px;
+}
+
 .breadcrumbs.banner-visible {
   top: calc(var(--header-height) + 3.5rem);
 }

package/assets/js/main.js

@@ -1468,6 +1468,11 @@ function generateBreadcrumbs() {
   const breadcrumbContainer = document.getElementById('breadcrumbs');
   if (!breadcrumbContainer) return;
   
+  // Check if this is a static build (has data attributes)
+  const isStaticBuild = breadcrumbContainer.classList.contains('breadcrumbs-static');
+  const buildDate = breadcrumbContainer.getAttribute('data-build-date');
+  const docBuilderVersion = breadcrumbContainer.getAttribute('data-doc-builder-version');
+  
   // Decode the URL to handle special characters and spaces
   const currentPath = decodeURIComponent(window.location.pathname);
   let pathSegments = currentPath.split('/').filter(segment => segment !== '');
@@ -1561,7 +1566,46 @@ function generateBreadcrumbs() {
     }
   }).join('<i class="fas fa-chevron-right breadcrumb-separator"></i>');
   
-  breadcrumbContainer.innerHTML = breadcrumbHTML;
+  // For static builds, add timestamp and PDF button to breadcrumbs
+  if (isStaticBuild && buildDate) {
+    // Check if we're on the homepage (only "Home" breadcrumb)
+    const isHomePage = pathSegments.length === 0 || 
+                       (pathSegments.length === 1 && (pathSegments[0] === 'index' || pathSegments[0] === 'README'));
+    
+    if (isHomePage) {
+      // On homepage, just show the timestamp and PDF button in a compact bar
+      const wrapperHTML = `
+        <div class="breadcrumbs-content breadcrumbs-homepage">
+          <div class="breadcrumbs-right">
+            <span class="breadcrumb-date" title="Built with doc-builder v${docBuilderVersion || ''}">Last updated: ${buildDate}</span>
+            <button class="breadcrumb-pdf-btn" onclick="exportToPDF()" title="Export to PDF" aria-label="Export to PDF">
+              <i class="fas fa-file-pdf"></i>
+            </button>
+          </div>
+        </div>
+      `;
+      breadcrumbContainer.innerHTML = wrapperHTML;
+      breadcrumbContainer.classList.add('breadcrumbs-minimal');
+    } else {
+      // Create a wrapper div for layout with breadcrumbs
+      const wrapperHTML = `
+        <div class="breadcrumbs-content">
+          <div class="breadcrumbs-left">
+            ${breadcrumbHTML}
+          </div>
+          <div class="breadcrumbs-right">
+            <span class="breadcrumb-date" title="Built with doc-builder v${docBuilderVersion || ''}">Last updated: ${buildDate}</span>
+            <button class="breadcrumb-pdf-btn" onclick="exportToPDF()" title="Export to PDF" aria-label="Export to PDF">
+              <i class="fas fa-file-pdf"></i>
+            </button>
+          </div>
+        </div>
+      `;
+      breadcrumbContainer.innerHTML = wrapperHTML;
+    }
+  } else {
+    breadcrumbContainer.innerHTML = breadcrumbHTML;
+  }
 }
 
 // Initialize tooltip positioning for navigation items

package/cli.js

@@ -36,6 +36,7 @@ ${chalk.yellow('What it does:')}
   • Deploys to Vercel with one command (zero configuration)
   • ${chalk.green.bold('NEW:')} Shows help by default, use 'deploy' to publish (v1.3.0+)
   • Optional authentication to protect private documentation
+  • Handles files with non-printable characters safely (v1.9.26+)
 
 ${chalk.yellow('Requirements:')}
   • Node.js 14+ installed
@@ -87,6 +88,10 @@ ${chalk.yellow('Examples:')}
   ${chalk.gray('$')} doc-builder build --no-auth              ${chalk.gray('# Build public site without authentication')}
   ${chalk.gray('$')} doc-builder build --no-static            ${chalk.gray('# Skip static output generation')}
   ${chalk.gray('$')} doc-builder build --static-dir public    ${chalk.gray('# Use custom static output directory')}
+
+${chalk.yellow('File Safety:')}
+  Files with non-printable characters in their names are automatically skipped
+  to prevent build failures. You'll see warnings for any problematic files.
 `)
   .action(async (options) => {
     const spinner = ora('Building documentation...').start();
@@ -628,6 +633,10 @@ ${chalk.yellow('Examples:')}
   ${chalk.gray('$')} doc-builder deploy --no-prod       ${chalk.gray('# Deploy preview only')}
   ${chalk.gray('$')} doc-builder deploy --no-auth       ${chalk.gray('# Deploy public site without authentication')}
 
+${chalk.yellow('File Safety:')}
+  Files with non-printable characters are automatically skipped during deployment
+  to prevent YAML parsing errors. You'll see warnings for any problematic files.
+
 ${chalk.yellow('First-time Vercel Setup:')}
   
   ${chalk.cyan('1. Install Vercel CLI:')}

package/doc-builder.config.js

@@ -1,5 +1,5 @@
 module.exports = {
-  "configVersion": "1.9.23",
+  "configVersion": "1.9.27",
   "docsDir": "docs",
   "outputDir": "html",
   "siteName": "@knowcode/doc-builder",

package/doc-builder.config.js.backup.1755031374829

@@ -0,0 +1,126 @@
+module.exports = {
+  "configVersion": "1.9.23",
+  "docsDir": "docs",
+  "outputDir": "html",
+  "siteName": "@knowcode/doc-builder",
+  "siteDescription": "Beautiful documentation with the least effort possible",
+  "favicon": "✨",
+  "features": {
+    "authentication": false,
+    "changelog": true,
+    "mermaid": true,
+    "mermaidEnhanced": true,
+    "tooltips": true,
+    "search": false,
+    "darkMode": true,
+    "phosphorIcons": true,
+    "phosphorWeight": "regular",
+    "phosphorSize": "1.2em",
+    "normalizeTitle": true,
+    "showPdfDownload": true,
+    "menuDefaultOpen": false,
+    "attachments": true,
+    "dynamicNavIcons": true,
+    "subtleColors": true,
+    "privateDirectoryAuth": false,
+    "banner": false,
+    "staticOutput": true
+  },
+  "staticOutputDir": "html-static",
+  "auth": {
+    "supabaseUrl": "https://xcihhnfcitjrwbynxmka.supabase.co",
+    "supabaseAnonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InhjaWhobmZjaXRqcndieW54bWthIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTM0Mzc2MzcsImV4cCI6MjA2OTAxMzYzN30.zvWp3JFIR8fBIiwuFF5gqOR_Kxb42baZS5fsBz60XOY"
+  },
+  "changelog": {
+    "daysBack": 14,
+    "enabled": true
+  },
+  "banner": {
+    "enabled": false,
+    "text": "This documentation is a preview version - some content may be incomplete",
+    "icon": "fas fa-exclamation-triangle",
+    "type": "warning",
+    "dismissible": true
+  },
+  "folderOrder": [],
+  "folderDescriptions": {},
+  "folderIcons": {},
+  "deployment": {
+    "platform": "vercel",
+    "outputDirectory": "html"
+  },
+  "seo": {
+    "enabled": true,
+    "siteUrl": "https://doc-builder-delta.vercel.app",
+    "author": "Lindsay Smith",
+    "twitterHandle": "@planbbackups",
+    "language": "en-US",
+    "keywords": [
+      "documentation",
+      "markdown",
+      "static site generator",
+      "vercel",
+      "notion-style"
+    ],
+    "titleTemplate": "{pageTitle} | {siteName}",
+    "autoKeywords": true,
+    "keywordLimit": 7,
+    "descriptionFallback": "smart",
+    "organization": {
+      "name": "Knowcode Ltd",
+      "url": "https://knowcode.tech",
+      "logo": ""
+    },
+    "ogImage": "/og-default.png",
+    "generateSitemap": true,
+    "generateRobotsTxt": true,
+    "customMetaTags": [
+      {
+        "name": "google-site-verification",
+        "content": "FtzcDTf5BQ9K5EfnGazQkgU2U4FiN3ITzM7gHwqUAqQ"
+      },
+      {
+        "name": "msvalidate.01",
+        "content": "B2D8C4C12C530D47AA962B24CAA09630"
+      }
+    ]
+  },
+  "attachmentTypes": [
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".xls",
+    ".xlsx",
+    ".csv",
+    ".ppt",
+    ".pptx",
+    ".txt",
+    ".rtf",
+    ".html",
+    ".htm",
+    ".zip",
+    ".tar",
+    ".gz",
+    ".7z",
+    ".rar",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".webp",
+    ".ico",
+    ".bmp",
+    ".json",
+    ".xml",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".mp4",
+    ".mp3",
+    ".wav",
+    ".avi",
+    ".mov"
+  ],
+  "productionUrl": "https://doc-builder-delta.vercel.app"
+};

package/html/README.html

@@ -101,8 +101,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-08-07T14:41:11.030Z",
-  "dateModified": "2025-08-07T14:41:11.030Z",
+  "datePublished": "2025-08-12T20:49:06.534Z",
+  "dateModified": "2025-08-12T20:49:06.534Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/README.html"
@@ -128,6 +128,7 @@
 </script>
 </head>
 <body>
+    
     <!-- Header -->
     <header class="header">
         <div class="header-content">
@@ -135,7 +136,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.9.23">Last updated: Aug 7, 2025, 02:41 PM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.9.27">Last updated: Aug 12, 2025, 08:49 PM UTC</span>
                 </div>
                 
                 
@@ -157,8 +158,9 @@
     
     
     
+    
     <!-- Breadcrumbs -->
-    <nav class="breadcrumbs" id="breadcrumbs">
+    <nav class="breadcrumbs " id="breadcrumbs" >
         <!-- Breadcrumbs will be generated by JavaScript -->
     </nav>
     

package/html/about-doc-builder.html

@@ -101,8 +101,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-08-07T14:41:11.041Z",
-  "dateModified": "2025-08-07T14:41:11.041Z",
+  "datePublished": "2025-08-12T20:49:06.547Z",
+  "dateModified": "2025-08-12T20:49:06.547Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/about-doc-builder.html"
@@ -128,6 +128,7 @@
 </script>
 </head>
 <body>
+    
     <!-- Header -->
     <header class="header">
         <div class="header-content">
@@ -135,7 +136,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.9.23">Last updated: Aug 7, 2025, 02:41 PM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.9.27">Last updated: Aug 12, 2025, 08:49 PM UTC</span>
                 </div>
                 
                 
@@ -157,8 +158,9 @@
     
     
     
+    
     <!-- Breadcrumbs -->
-    <nav class="breadcrumbs" id="breadcrumbs">
+    <nav class="breadcrumbs " id="breadcrumbs" >
         <!-- Breadcrumbs will be generated by JavaScript -->
     </nav>
     

package/html/css/notion-style.css

@@ -534,6 +534,12 @@ pre code {
   overflow: hidden;
 }
 
+/* Static build main wrapper - adjust for no header and smaller breadcrumb */
+.breadcrumbs-static ~ .main-wrapper {
+  height: calc(100vh - 28px);
+  margin-top: 28px;
+}
+
 .main-wrapper.banner-visible {
   height: calc(100vh - var(--header-height) - var(--breadcrumb-height) - 3.5rem);
   margin-top: calc(var(--header-height) + var(--breadcrumb-height) + 3.5rem);
@@ -990,6 +996,76 @@ tr:hover {
   gap: var(--space-2);
 }
 
+/* Static build breadcrumbs - no header so top is 0 */
+.breadcrumbs-static {
+  top: 0 !important;
+  height: auto !important;
+  min-height: 28px !important;
+  padding: 0.15rem var(--space-6) !important;
+}
+
+/* Breadcrumbs content wrapper for static builds */
+.breadcrumbs-content {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+}
+
+.breadcrumbs-left {
+  display: flex;
+  align-items: center;
+  gap: 0;
+}
+
+.breadcrumbs-right {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+/* Timestamp in breadcrumbs */
+.breadcrumb-date {
+  color: var(--color-text-tertiary);
+  font-size: var(--text-xs);
+  white-space: nowrap;
+}
+
+/* PDF button in breadcrumbs */
+.breadcrumb-pdf-btn {
+  background: none;
+  border: none;
+  color: var(--color-text-secondary);
+  cursor: pointer;
+  padding: var(--space-1) var(--space-2);
+  border-radius: var(--radius-md);
+  transition: all 0.2s;
+  font-size: 1rem;
+}
+
+.breadcrumb-pdf-btn:hover {
+  background: var(--color-bg-tertiary);
+  color: var(--color-text-primary);
+}
+
+/* Minimal breadcrumbs for homepage - even more compact */
+.breadcrumbs-minimal.breadcrumbs-static {
+  height: auto !important;
+  min-height: 24px !important;
+  padding: 0.1rem var(--space-6) !important;
+}
+
+/* Homepage breadcrumbs content - right-aligned only */
+.breadcrumbs-homepage {
+  justify-content: flex-end !important;
+}
+
+/* Adjust main wrapper for minimal breadcrumbs */
+.breadcrumbs-minimal.breadcrumbs-static ~ .main-wrapper {
+  height: calc(100vh - 24px);
+  margin-top: 24px;
+}
+
 .breadcrumbs.banner-visible {
   top: calc(var(--header-height) + 3.5rem);
 }

package/html/documentation-index.html

@@ -101,8 +101,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-08-07T14:41:11.044Z",
-  "dateModified": "2025-08-07T14:41:11.044Z",
+  "datePublished": "2025-08-12T20:49:06.551Z",
+  "dateModified": "2025-08-12T20:49:06.551Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/documentation-index.html"
@@ -128,6 +128,7 @@
 </script>
 </head>
 <body>
+    
     <!-- Header -->
     <header class="header">
         <div class="header-content">
@@ -135,7 +136,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.9.23">Last updated: Aug 7, 2025, 02:41 PM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.9.27">Last updated: Aug 12, 2025, 08:49 PM UTC</span>
                 </div>
                 
                 
@@ -157,8 +158,9 @@
     
     
     
+    
     <!-- Breadcrumbs -->
-    <nav class="breadcrumbs" id="breadcrumbs">
+    <nav class="breadcrumbs " id="breadcrumbs" >
         <!-- Breadcrumbs will be generated by JavaScript -->
     </nav>
     

package/html/guides/authentication-default-change.html

@@ -101,8 +101,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-08-07T14:41:11.048Z",
-  "dateModified": "2025-08-07T14:41:11.048Z",
+  "datePublished": "2025-08-12T20:49:06.556Z",
+  "dateModified": "2025-08-12T20:49:06.556Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/guides/authentication-default-change.html"
@@ -134,6 +134,7 @@
 </script>
 </head>
 <body>
+    
     <!-- Header -->
     <header class="header">
         <div class="header-content">
@@ -141,7 +142,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.9.23">Last updated: Aug 7, 2025, 02:41 PM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.9.27">Last updated: Aug 12, 2025, 08:49 PM UTC</span>
                 </div>
                 
                 
@@ -163,8 +164,9 @@
     
     
     
+    
     <!-- Breadcrumbs -->
-    <nav class="breadcrumbs" id="breadcrumbs">
+    <nav class="breadcrumbs " id="breadcrumbs" >
         <!-- Breadcrumbs will be generated by JavaScript -->
     </nav>
     

package/html/guides/authentication-guide.html

@@ -101,8 +101,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-08-07T14:41:11.051Z",
-  "dateModified": "2025-08-07T14:41:11.051Z",
+  "datePublished": "2025-08-12T20:49:06.560Z",
+  "dateModified": "2025-08-12T20:49:06.560Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/guides/authentication-guide.html"
@@ -134,6 +134,7 @@
 </script>
 </head>
 <body>
+    
     <!-- Header -->
     <header class="header">
         <div class="header-content">
@@ -141,7 +142,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.9.23">Last updated: Aug 7, 2025, 02:41 PM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.9.27">Last updated: Aug 12, 2025, 08:49 PM UTC</span>
                 </div>
                 
                 
@@ -163,8 +164,9 @@
     
     
     
+    
     <!-- Breadcrumbs -->
-    <nav class="breadcrumbs" id="breadcrumbs">
+    <nav class="breadcrumbs " id="breadcrumbs" >
         <!-- Breadcrumbs will be generated by JavaScript -->
     </nav>