@knowcode/doc-builder 1.9.19 → 1.9.21

package/lib/core-builder.js

@@ -361,6 +361,21 @@ function generateFaviconTag(favicon) {
   return `<link rel="icon" href="${favicon}">`;
 }
 
+// Generate static HTML (without authentication)
+function generateStaticHTML(title, content, navigation, currentPath = '', config = {}, originalContent = '', frontMatter = {}) {
+  // Use regular generateHTML but force disable auth features
+  const staticConfig = {
+    ...config,
+    features: {
+      ...config.features,
+      authentication: false,
+      privateDirectoryAuth: false
+    }
+  };
+  
+  return generateHTML(title, content, navigation, currentPath, staticConfig, originalContent, frontMatter);
+}
+
 // Generate HTML from template
 function generateHTML(title, content, navigation, currentPath = '', config = {}, originalContent = '', frontMatter = {}) {
   const depth = currentPath.split('/').filter(p => p).length;
@@ -668,6 +683,11 @@ function buildNavigationStructure(files, currentFile, config = {}) {
   
   // Helper function to generate file title
   const generateFileTitle = (file, parentDisplayName, level) => {
+    // First check for front matter title
+    if (file.frontMatter?.title) {
+      return file.frontMatter.title;
+    }
+    
     let title = file.displayName;
     
     if (file.displayName === 'README') {
@@ -868,11 +888,17 @@ function buildNavigationStructure(files, currentFile, config = {}) {
 }
 
 // Process single markdown file
-async function processMarkdownFile(filePath, outputPath, allFiles, config) {
+async function processMarkdownFile(filePath, outputPath, allFiles, config, useStaticHTML = false) {
   const rawContent = await fs.readFile(filePath, 'utf-8');
   const fileName = path.basename(filePath, '.md');
   const relativePath = path.relative(config.docsDir, filePath);
-  const urlPath = relativePath.replace(/\.md$/, '.html').replace(/\\/g, '/');
+  // Encode special characters in URL but keep slashes
+  const urlPath = relativePath
+    .replace(/\.md$/, '.html')
+    .replace(/\\/g, '/')
+    .split('/')
+    .map(segment => encodeURIComponent(segment))
+    .join('/');
   
   // Parse front matter
   const { data: frontMatter, content } = matter(rawContent);
@@ -895,7 +921,9 @@ async function processMarkdownFile(filePath, outputPath, allFiles, config) {
   const navigation = buildNavigationStructure(allFiles, urlPath, config);
   
   // Generate full HTML (pass original content and front matter for SEO)
-  const html = generateHTML(title, htmlContent, navigation, urlPath, config, content, frontMatter);
+  const html = useStaticHTML 
+    ? generateStaticHTML(title, htmlContent, navigation, urlPath, config, content, frontMatter)
+    : generateHTML(title, htmlContent, navigation, urlPath, config, content, frontMatter);
   
   // Write file
   await fs.ensureDir(path.dirname(outputPath));
@@ -905,7 +933,7 @@ async function processMarkdownFile(filePath, outputPath, allFiles, config) {
 }
 
 // Get all markdown files
-async function getAllMarkdownFiles(dir, baseDir = dir) {
+async function getAllMarkdownFiles(dir, baseDir = dir, options = {}) {
   const files = [];
   const items = await fs.readdir(dir);
   
@@ -913,12 +941,23 @@ async function getAllMarkdownFiles(dir, baseDir = dir) {
     const fullPath = path.join(dir, item);
     const stat = await fs.stat(fullPath);
     
+    // Skip private directories if excludePrivate is true
+    if (stat.isDirectory() && options.excludePrivate && item === 'private') {
+      continue;
+    }
+    
     if (stat.isDirectory() && !item.startsWith('.') && !item.startsWith('_')) {
-      const subFiles = await getAllMarkdownFiles(fullPath, baseDir);
+      const subFiles = await getAllMarkdownFiles(fullPath, baseDir, options);
       files.push(...subFiles);
     } else if (item.endsWith('.md') && !item.startsWith('_')) {
       const relativePath = path.relative(baseDir, fullPath);
-      const urlPath = relativePath.replace(/\.md$/, '.html').replace(/\\/g, '/');
+      // Encode special characters in URL but keep slashes
+      const urlPath = relativePath
+        .replace(/\.md$/, '.html')
+        .replace(/\\/g, '/')
+        .split('/')
+        .map(segment => encodeURIComponent(segment))
+        .join('/');
       const displayName = smartCapitalize(path.basename(item, '.md'));
       
       // Read file to extract summary and status
@@ -933,6 +972,11 @@ async function getAllMarkdownFiles(dir, baseDir = dir) {
                        relativePath.startsWith('private/') || 
                        relativePath.startsWith('private\\');
       
+      // Skip private files if excludePrivate is true
+      if (options.excludePrivate && isPrivate) {
+        continue;
+      }
+      
       files.push({
         path: fullPath,
         relativePath,
@@ -1234,6 +1278,122 @@ async function buildDocumentation(config) {
     }
   }
   
+  // Generate static version if enabled
+  if (config.features?.staticOutput !== false) {
+    console.log(chalk.blue('\n🌐 Generating static version (no auth, no private content)...'));
+    
+    const staticOutputDir = path.join(process.cwd(), config.staticOutputDir || 'html-static');
+    
+    // Ensure static output directory exists
+    await fs.ensureDir(staticOutputDir);
+    
+    // Get files excluding private directories
+    const staticFiles = await getAllMarkdownFiles(docsDir, docsDir, { excludePrivate: true });
+    console.log(chalk.gray(`  Found ${staticFiles.length} public files (private files excluded)`));
+    
+    // Process files for static output
+    for (const file of staticFiles) {
+      const outputPath = path.join(staticOutputDir, file.urlPath);
+      await processMarkdownFile(file.path, outputPath, staticFiles, config, true);
+    }
+    
+    // Copy assets to static directory
+    const assetsDir = path.join(__dirname, '../assets');
+    const cssSource = path.join(assetsDir, 'css');
+    const jsSource = path.join(assetsDir, 'js');
+    
+    if (fs.existsSync(cssSource)) {
+      await fs.copy(cssSource, path.join(staticOutputDir, 'css'), { overwrite: true });
+    }
+    
+    if (fs.existsSync(jsSource)) {
+      await fs.copy(jsSource, path.join(staticOutputDir, 'js'), { overwrite: true });
+      // Don't generate auth.js for static version
+    }
+    
+    // Copy 404.html for handling .md redirects
+    const notFoundSource = path.join(assetsDir, '404.html');
+    if (fs.existsSync(notFoundSource)) {
+      await fs.copy(notFoundSource, path.join(staticOutputDir, '404.html'), { overwrite: true });
+    }
+    
+    // Create index.html from README.html or generate default
+    const staticIndexPath = path.join(staticOutputDir, 'index.html');
+    const staticReadmePath = path.join(staticOutputDir, 'README.html');
+    
+    if (fs.existsSync(staticReadmePath)) {
+      await fs.copy(staticReadmePath, staticIndexPath);
+    } else if (staticFiles.length > 0) {
+      // Generate a default index that lists available pages
+      const defaultIndex = await createDefaultIndexPage(staticOutputDir, config, packageJson.version);
+      await fs.writeFile(staticIndexPath, defaultIndex);
+    }
+    
+    // Copy attachments to static directory if enabled
+    if (config.features?.attachments !== false) {
+      const attachmentTypes = config.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'
+      ];
+      
+      try {
+        // Get attachment files excluding private directories
+        const allAttachmentFiles = await getAllAttachmentFiles(docsDir, docsDir, attachmentTypes);
+        const staticAttachmentFiles = [];
+        for (const file of allAttachmentFiles) {
+          if (!file.relativePath.startsWith('private/') && !file.relativePath.startsWith('private\\')) {
+            staticAttachmentFiles.push(file);
+          }
+        }
+        
+        if (staticAttachmentFiles.length > 0) {
+          await copyAttachmentFiles(staticAttachmentFiles, docsDir, staticOutputDir);
+        }
+      } catch (error) {
+        console.warn(chalk.yellow(`Warning: Error copying attachments to static output: ${error.message}`));
+      }
+    }
+    
+    // Generate SEO files for static version if enabled
+    if (config.seo?.enabled && config.seo?.siteUrl) {
+      // Collect all HTML files for sitemap
+      const staticPages = [];
+      const walkDir = (dir, baseDir = '') => {
+        const items = fs.readdirSync(dir);
+        items.forEach(item => {
+          const fullPath = path.join(dir, item);
+          const stat = fs.statSync(fullPath);
+          if (stat.isDirectory()) {
+            walkDir(fullPath, path.join(baseDir, item));
+          } else if (item.endsWith('.html')) {
+            staticPages.push({
+              path: baseDir ? path.join(baseDir, item) : item,
+              modified: stat.mtime
+            });
+          }
+        });
+      };
+      
+      walkDir(staticOutputDir);
+      
+      if (config.seo.generateSitemap) {
+        await generateSitemap(staticPages, config.seo.siteUrl, staticOutputDir);
+      }
+      
+      if (config.seo.generateRobotsTxt) {
+        await generateRobotsTxt(config.seo.siteUrl, staticOutputDir, {
+          hasAuthentication: false
+        });
+      }
+    }
+    
+    console.log(chalk.green(`✅ Static version generated in ${config.staticOutputDir || 'html-static'}/`));
+  }
+  
   console.log(chalk.green('\n✅ Documentation build complete!'));
 }
 
@@ -1554,6 +1714,7 @@ module.exports = {
   buildDocumentation,
   processMarkdownContent,
   generateHTML,
+  generateStaticHTML,
   createPlaceholderReadme,
   createDefaultIndexPage
 };

package/package.json

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