@knowcode/doc-builder 1.2.6 → 1.2.7

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.2.7] - 2025-07-19
+
+### Added
+- Comprehensive debugging output showing package version and file existence checks
+- Support for `index.md` as primary source for index.html (higher priority than README.md)
+- Informative default index.html page when no README.md or index.md exists
+- List of available HTML files in default index page
+- Version and debug information in generated pages
+
+### Fixed
+- Fixed infinite redirect loop in deploy.js when no README.html exists
+- Improved index.html creation reliability with better file detection
+- Better error messages and guidance when documentation is missing
+
+### Changed
+- Enhanced logging throughout build and deploy processes
+- Redirect to first available HTML file instead of infinite loop
+- More descriptive console output during index.html creation
+
+## [1.2.6] - 2025-07-19
+
+### Fixed
+- **Index.html creation** - Fixed root URL not serving documentation by creating index.html from README.html
+- Added index.html creation in both build and deploy processes for reliability
+
 ## [1.2.5] - 2025-07-19
 
 ### Fixed

package/lib/core-builder.js

@@ -448,6 +448,10 @@ async function buildDocumentation(config) {
   const docsDir = path.join(process.cwd(), config.docsDir);
   const outputDir = path.join(process.cwd(), config.outputDir);
   
+  // Log version for debugging
+  const packageJson = require('../package.json');
+  console.log(chalk.blue(`📦 Using @knowcode/doc-builder v${packageJson.version}`));
+  
   // Check and create placeholder README.md if missing
   console.log(chalk.blue('📋 Checking documentation structure...'));
   const readmeGenerated = await createPlaceholderReadme(docsDir, config);
@@ -490,12 +494,28 @@ async function buildDocumentation(config) {
     await createAuthPages(outputDir, config);
   }
   
-  // Create index.html from README.html if it doesn't exist
+  // Create index.html from index.html, README.html, or generate default
   const indexPath = path.join(outputDir, 'index.html');
+  const indexSourcePath = path.join(outputDir, 'index.html'); // from index.md
   const readmePath = path.join(outputDir, 'README.html');
-  if (!fs.existsSync(indexPath) && fs.existsSync(readmePath)) {
-    await fs.copy(readmePath, indexPath);
-    console.log(chalk.green('✅ Created index.html from README.html'));
+  
+  console.log(chalk.blue('📄 Checking for index.html creation...'));
+  console.log(chalk.gray(`  - index.html exists: ${fs.existsSync(indexPath)})`));
+  console.log(chalk.gray(`  - README.html exists: ${fs.existsSync(readmePath)})`));
+  
+  if (!fs.existsSync(indexPath)) {
+    if (fs.existsSync(readmePath)) {
+      await fs.copy(readmePath, indexPath);
+      console.log(chalk.green('✅ Created index.html from README.html'));
+    } else {
+      // No README.html, create informative default page
+      console.log(chalk.yellow('⚠️  No README.html found, creating default index.html'));
+      const defaultIndex = await createDefaultIndexPage(outputDir, config, packageJson.version);
+      await fs.writeFile(indexPath, defaultIndex);
+      console.log(chalk.green('✅ Created default index.html with instructions'));
+    }
+  } else {
+    console.log(chalk.gray('ℹ️  index.html already exists (likely from index.md)'));
   }
   
   console.log(chalk.green('✅ Documentation build complete!'));
@@ -504,12 +524,19 @@ async function buildDocumentation(config) {
 // Create placeholder README.md if missing
 async function createPlaceholderReadme(docsDir, config) {
   const readmePath = path.join(docsDir, 'README.md');
+  const indexPath = path.join(docsDir, 'index.md');
   
-  // Check if README.md already exists
+  // Check if README.md or index.md already exists
   if (fs.existsSync(readmePath)) {
+    console.log(chalk.gray('  ✓ README.md found'));
     return false; // README already exists, no need to create
   }
   
+  if (fs.existsSync(indexPath)) {
+    console.log(chalk.gray('  ✓ index.md found'));
+    return false; // index.md exists, no need for README
+  }
+  
   const siteName = config.siteName || 'Documentation';
   const currentDate = new Date().toISOString().split('T')[0];
   
@@ -672,9 +699,177 @@ async function createAuthPages(outputDir, config) {
   await fs.writeFile(path.join(outputDir, 'logout.html'), logoutHTML);
 }
 
+// Create default index page when no documentation exists
+async function createDefaultIndexPage(outputDir, config, version) {
+  const siteName = config.siteName || 'Documentation';
+  const currentDate = new Date().toISOString();
+  
+  // List all HTML files in the output directory
+  const htmlFiles = [];
+  async function findHtmlFiles(dir, baseDir = dir) {
+    const items = await fs.readdir(dir);
+    for (const item of items) {
+      const fullPath = path.join(dir, item);
+      const stat = await fs.stat(fullPath);
+      if (stat.isDirectory() && !item.startsWith('.')) {
+        await findHtmlFiles(fullPath, baseDir);
+      } else if (item.endsWith('.html') && item !== 'index.html' && item !== 'login.html' && item !== 'logout.html') {
+        const relativePath = path.relative(baseDir, fullPath);
+        htmlFiles.push(relativePath);
+      }
+    }
+  }
+  
+  await findHtmlFiles(outputDir);
+  
+  let fileListHtml = '';
+  if (htmlFiles.length > 0) {
+    fileListHtml = `
+    <div class="existing-files">
+      <h2>📁 Available Documentation</h2>
+      <p>The following documentation files were found:</p>
+      <ul>
+        ${htmlFiles.map(file => `<li><a href="${file}">${file}</a></li>`).join('\n        ')}
+      </ul>
+    </div>`;
+  }
+  
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <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;
+        margin: 50px auto;
+        padding: 40px;
+        background: var(--bg-secondary);
+        border-radius: 12px;
+        box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+      }
+      .welcome-container h1 {
+        color: var(--text-primary);
+        margin-bottom: 20px;
+      }
+      .welcome-container h2 {
+        color: var(--text-primary);
+        margin-top: 30px;
+        margin-bottom: 15px;
+      }
+      .welcome-container p {
+        color: var(--text-secondary);
+        line-height: 1.6;
+        margin-bottom: 15px;
+      }
+      .welcome-container pre {
+        background: var(--bg-tertiary);
+        padding: 20px;
+        border-radius: 8px;
+        overflow-x: auto;
+        margin: 20px 0;
+      }
+      .welcome-container code {
+        font-family: 'JetBrains Mono', monospace;
+        font-size: 14px;
+      }
+      .welcome-container ul {
+        margin: 20px 0;
+        padding-left: 30px;
+      }
+      .welcome-container li {
+        margin: 8px 0;
+      }
+      .version-info {
+        margin-top: 40px;
+        padding-top: 20px;
+        border-top: 1px solid var(--border-color);
+        font-size: 12px;
+        color: var(--text-tertiary);
+      }
+      .existing-files {
+        background: var(--bg-primary);
+        padding: 20px;
+        border-radius: 8px;
+        margin: 30px 0;
+      }
+      .existing-files a {
+        color: var(--link-color);
+        text-decoration: none;
+      }
+      .existing-files a:hover {
+        text-decoration: underline;
+      }
+    </style>
+</head>
+<body>
+    <div class="welcome-container">
+      <h1>📚 Welcome to ${siteName}</h1>
+      
+      <p>This documentation site was generated by <strong>@knowcode/doc-builder</strong>. To add your own content, follow the instructions below.</p>
+      
+      <h2>🚀 Getting Started</h2>
+      
+      <p>To create your documentation homepage, create either of these files in your <code>docs/</code> directory:</p>
+      
+      <ul>
+        <li><code>index.md</code> - Primary homepage (highest priority)</li>
+        <li><code>README.md</code> - Alternative homepage</li>
+      </ul>
+      
+      <h2>📝 Example Content</h2>
+      
+      <p>Create <code>docs/index.md</code> with content like:</p>
+      
+      <pre><code># Welcome to My Project
+
+This is the homepage for my documentation.
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Getting Started
+
+1. Install the package
+2. Configure your settings
+3. Start building!</code></pre>
+      
+      <h2>🔧 Next Steps</h2>
+      
+      <ol>
+        <li>Create <code>docs/index.md</code> or <code>docs/README.md</code></li>
+        <li>Add more markdown files for additional pages</li>
+        <li>Rebuild: <code>npx @knowcode/doc-builder build</code></li>
+        <li>Deploy: <code>npx @knowcode/doc-builder deploy</code></li>
+      </ol>
+      
+      ${fileListHtml}
+      
+      <div class="version-info">
+        <p><strong>Debug Information:</strong></p>
+        <ul>
+          <li>doc-builder version: ${version}</li>
+          <li>Generated: ${currentDate}</li>
+          <li>Site name: ${siteName}</li>
+          <li>No index.md or README.md found in docs directory</li>
+        </ul>
+      </div>
+    </div>
+</body>
+</html>`;
+}
+
 module.exports = {
   buildDocumentation,
   processMarkdownContent,
   generateHTML,
-  createPlaceholderReadme
+  createPlaceholderReadme,
+  createDefaultIndexPage
 };

package/lib/deploy.js

@@ -341,23 +341,41 @@ async function deployToVercel(config, isProd = false) {
 async function prepareDeployment(config) {
   const outputDir = path.join(process.cwd(), config.outputDir || 'html');
   
+  // Log version for debugging
+  const packageJson = require('../package.json');
+  console.log(chalk.blue(`\n📦 Preparing deployment with @knowcode/doc-builder v${packageJson.version}`));
+  
   // Create index.html from README.html if needed
   const indexPath = path.join(outputDir, 'index.html');
+  console.log(chalk.gray(`  - Checking index.html: ${fs.existsSync(indexPath) ? 'exists' : 'missing'}}`));
+  
   if (!fs.existsSync(indexPath)) {
     const readmePath = path.join(outputDir, 'README.html');
+    console.log(chalk.gray(`  - Checking README.html: ${fs.existsSync(readmePath) ? 'exists' : 'missing'}}`));
+    
     if (fs.existsSync(readmePath)) {
       // Copy README.html to index.html for proper root page
       fs.copyFileSync(readmePath, indexPath);
       console.log(chalk.green('✅ Created index.html from README.html'));
     } else {
-      // 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>
+      // If no README.html, find first available HTML file or create informative page
+      console.log(chalk.yellow('⚠️  No README.html found, looking for other HTML files...'));
+      
+      // Find first available HTML file
+      const htmlFiles = fs.readdirSync(outputDir)
+        .filter(file => file.endsWith('.html') && file !== 'index.html' && file !== 'login.html' && file !== 'logout.html')
+        .sort();
+      
+      if (htmlFiles.length > 0) {
+        // Redirect to first HTML file
+        const firstFile = htmlFiles[0];
+        console.log(chalk.green(`✅ Creating index.html redirect to ${firstFile}`));
+        const redirectIndex = `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="refresh" content="0; url=./">
+  <meta http-equiv="refresh" content="0; url=${firstFile}">
   <title>${config.siteName || 'Documentation'}</title>
   <link rel="stylesheet" href="/css/style.css">
   <link rel="stylesheet" href="/css/notion-style.css">
@@ -365,15 +383,39 @@ async function prepareDeployment(config) {
 <body>
   <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>
+    <p>Redirecting to documentation...</p>
+    <p><a href="${firstFile}" style="color: #0366d6;">Click here if not redirected automatically</a></p>
   </div>
 </body>
 </html>`;
-      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'));
+        fs.writeFileSync(indexPath, redirectIndex);
+        console.log(chalk.green(`✅ Created index.html redirect to ${firstFile}`));
+      } else {
+        // No HTML files at all - this should never happen after build
+        console.log(chalk.red('❌ No HTML files found in output directory!'));
+        console.log(chalk.yellow('📌 This indicates a build issue. Please run: npx @knowcode/doc-builder build'));
+        
+        // Create emergency fallback page
+        const { createDefaultIndexPage } = require('./core-builder');
+        const fallbackIndex = await createDefaultIndexPage(outputDir, config, packageJson.version);
+        fs.writeFileSync(indexPath, fallbackIndex);
+        console.log(chalk.green('✅ Created fallback index.html with instructions'));
+      }
     }
+  } else {
+    console.log(chalk.gray('  ✓ index.html already exists'));
+  }
+  
+  // Final check - log what files exist
+  console.log(chalk.blue('\n📁 Final deployment state:'));
+  const finalFiles = fs.readdirSync(outputDir)
+    .filter(file => file.endsWith('.html'))
+    .slice(0, 5); // Show first 5 HTML files
+  finalFiles.forEach(file => {
+    console.log(chalk.gray(`  - ${file}`));
+  });
+  if (fs.readdirSync(outputDir).filter(f => f.endsWith('.html')).length > 5) {
+    console.log(chalk.gray(`  - ... and ${fs.readdirSync(outputDir).filter(f => f.endsWith('.html')).length - 5} more HTML files`));
   }
 }
 

package/package.json

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