@knowcode/doc-builder 1.5.10 → 1.5.12

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.5.12] - 2025-07-22
+
+### Documentation
+- 📚 **Updated all Vercel documentation** for the simplified setup process
+- ✨ **Rewrote vercel-first-time-setup-guide.md** with streamlined 6-step process
+- 🔧 **Updated vercel-cli-setup-guide.md** to focus on installation and advanced usage
+- 📝 **Simplified README.md deployment section** to 4 clear steps
+- 🐛 **Updated troubleshooting-guide.md** with new deployment solutions
+- 🎯 **Removed references to complex prompts** and confusing options
+- 📖 **Added 'What Changed' section** highlighting improvements
+
+### Documentation Improvements
+- No more confusing "Found project xyz/html" prompts
+- No more root directory confusion
+- Clear, straightforward deployment flow
+- Better error messages and solutions
+
+## [1.5.11] - 2025-07-22
+
+### Fixed
+- Fixed Vercel deployment error: "routes cannot be present with rewrites"
+- Replaced deprecated `routes` configuration with modern `rewrites` in vercel.json
+- Deployment now works correctly with Vercel's latest API
+
+### Improved
+- Dramatically simplified deployment prompts and warnings
+- Reduced verbosity of console output during deployment
+- Made setup instructions clearer and less intimidating
+- Removed redundant and scary "CRITICAL WARNING" messages
+- Streamlined the first-time deployment experience
+
+### Changed
+- vercel.json now uses `rewrites` instead of deprecated `routes` property
+- Cleaner, more professional console output throughout deployment process
+- Better error messages that are helpful rather than alarming
+
 ## [1.5.10] - 2025-07-22
 
 ### Fixed

package/README.md

@@ -86,22 +86,23 @@ doc-builder deploy
 
 ## First-Time Vercel Deployment
 
-When deploying for the first time, doc-builder will:
+The deployment process is now simpler than ever:
 
-1. Check if Vercel CLI is installed
-2. Guide you through project setup
-3. Create `vercel.json` configuration
-4. Link your project to Vercel
-5. Show important reminders about Vercel settings
+1. Run `npx @knowcode/doc-builder deploy`
+2. Answer a few simple questions (project name, etc.)
+3. Vercel CLI automatically detects and configures everything
+4. Get your live URL in seconds!
 
-### Important Vercel Settings
+### Making Your Docs Public
 
-After deployment, go to your Vercel dashboard:
+After deployment, if you want public access:
 
-1. Navigate to **Project Settings > General**
-2. Under **Security**, find **Deployment Protection**
-3. Set to **Disabled** for public access
-4. Or configure authentication for private docs
+1. Go to [Vercel Dashboard](https://vercel.com/dashboard)
+2. Click your project → Settings → Deployment Protection
+3. Set **Vercel Authentication** to **Disabled**
+4. Save changes
+
+See the [First-Time Setup Guide](docs/vercel-first-time-setup-guide.md) for a complete walkthrough.
 
 ## Configuration (optional - can be managed with CLI)
 

package/cli.js

@@ -683,20 +683,12 @@ ${chalk.yellow('Troubleshooting:')}
       const vercelProjectPath = path.join(outputPath, '.vercel', 'project.json');
       if (!fs.existsSync(vercelProjectPath)) {
         spinner.stop();
-        console.log(chalk.yellow('\n🚀 First time deploying to Vercel!\n'));
+        console.log(chalk.blue('\n🚀 First time deploying to Vercel!\n'));
         
-        // Show critical warning about Root Directory
-        console.log(chalk.bgRed.white.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-        console.log(chalk.bgRed.white.bold(' ⚠️  CRITICAL WARNING - READ BEFORE CONTINUING! '));
-        console.log(chalk.bgRed.white.bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
-        
-        console.log(chalk.yellow.bold('During setup, if Vercel asks about Root Directory:'));
-        console.log(chalk.red.bold('• LEAVE IT EMPTY (blank)'));
-        console.log(chalk.red.bold('• DO NOT ENTER "html"'));
-        console.log(chalk.red.bold('• We are ALREADY deploying from the html folder!\n'));
-        
-        console.log(chalk.white('Setting Root Directory to "html" will cause errors.'));
-        console.log(chalk.white('You\'ll need to fix it in project settings later.\n'));
+        console.log(chalk.yellow('📝 Important: When asked about settings:'));
+        console.log(chalk.gray('   • Root Directory: ') + chalk.green('leave empty'));
+        console.log(chalk.gray('   • We handle the build process for you'));
+        console.log();
         
         const setupConfirm = await prompts({
           type: 'confirm',

package/lib/deploy.js

@@ -94,14 +94,10 @@ async function setupVercelProject(config) {
         ]
       }
     ],
-    "routes": [
+    "rewrites": [
       {
-        "handle": "filesystem"
-      },
-      {
-        "src": "/(.*)",
-        "status": 404,
-        "dest": "/404.html"
+        "source": "/(.*)",
+        "destination": "/404.html"
       }
     ]
   };
@@ -130,41 +126,17 @@ async function setupVercelProject(config) {
     }
   }
   
-  // Run Vercel setup with prominent instructions
-  console.log(chalk.blue('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-  console.log(chalk.blue('🔗 Linking to Vercel - IMPORTANT INSTRUCTIONS'));
-  console.log(chalk.blue('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
-  
-  console.log(chalk.yellow('⚠️  FOLLOW THESE ANSWERS CAREFULLY:\n'));
-  
-  console.log(chalk.white('1️⃣  ') + chalk.green('Set up "~/Documents/.../html"?'));
-  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold('YES') + '\n');
-  
-  console.log(chalk.white('2️⃣  ') + chalk.green('Which scope should contain your project?'));
-  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold('Select your account') + ' (usually your username)\n');
-  
-  console.log(chalk.white('3️⃣  ') + chalk.green('Found project "username/html". Link to it?'));
-  console.log(chalk.white('   👉 Answer: ') + chalk.red.bold('NO') + ' (this is NOT your project!)\n');
-  
-  console.log(chalk.white('4️⃣  ') + chalk.green('Link to different existing project?'));
-  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold('YES') + ' if you have an existing project');
-  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold('NO') + ' to create new project\n');
-  
-  console.log(chalk.white('5️⃣  ') + chalk.yellow('If you answered YES to #4:'));
-  console.log(chalk.white('   ') + chalk.green('What\'s the name of your existing project?'));
-  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold(answers.projectName) + ' (your existing project name)\n');
-  
-  console.log(chalk.white('5️⃣  ') + chalk.yellow('If you answered NO to #4:'));
-  console.log(chalk.white('   ') + chalk.green('What is your project name?'));
-  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold(answers.projectName) + ' (e.g., "my-docs" or "gasworld")\n');
-  
-  console.log(chalk.red.bold('⚠️  CRITICAL WARNING ABOUT ROOT DIRECTORY:\n'));
-  console.log(chalk.bgRed.white.bold(' If Vercel asks about Root Directory or shows it in settings: '));
-  console.log(chalk.bgRed.white.bold(' LEAVE IT COMPLETELY EMPTY! DO NOT ENTER "html"! '));
-  console.log(chalk.white('\nWe are already in the html folder - setting Root Directory'));
-  console.log(chalk.white('to "html" will cause "html/html does not exist" errors!\n'));
+  // Run Vercel setup with simplified instructions
+  console.log(chalk.blue('\n🔗 Linking to Vercel...\n'));
   
-  console.log(chalk.blue('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
+  console.log(chalk.yellow('When Vercel CLI asks:'));
+  console.log(chalk.gray('• Set up and deploy: ') + chalk.green('YES'));
+  console.log(chalk.gray('• Which scope: ') + chalk.green('Select your account'));
+  console.log(chalk.gray('• Link to existing project: ') + chalk.green('YES/NO') + chalk.gray(' (your choice)'));
+  console.log(chalk.gray('• Project name: ') + chalk.green(answers.projectName));
+  console.log(chalk.gray('• Directory with code: ') + chalk.yellow('./') + chalk.gray(' (current directory)'));
+  console.log(chalk.gray('• Modify settings: ') + chalk.red('NO'));
+  console.log();
   
   try {
     // Run vercel link from the output directory
@@ -177,37 +149,19 @@ async function setupVercelProject(config) {
     process.exit(1);
   }
   
-  // Important reminders for Vercel settings
-  console.log(chalk.red('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-  console.log(chalk.red.bold('🚨 CRITICAL POST-SETUP STEP - DO THIS NOW!'));
-  console.log(chalk.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
-  
-  console.log(chalk.yellow.bold('Vercel may have set Root Directory incorrectly!\n'));
-  
-  console.log(chalk.white.bold('1. GO TO YOUR PROJECT SETTINGS NOW:'));
-  console.log(chalk.cyan(`   https://vercel.com/${answers.projectName}/settings\n`));
-  
-  console.log(chalk.white.bold('2. Find "Root Directory" under "Build & Development Settings"\n'));
-  
-  console.log(chalk.white.bold('3. CHECK THE VALUE:'));
-  console.log(chalk.green('   ✅ CORRECT: ') + chalk.green.bold('Empty (blank) or "./"'));
-  console.log(chalk.red('   ❌ WRONG: ') + chalk.red.bold('"html" or any other value\n'));
-  
-  console.log(chalk.white.bold('4. IF IT SAYS "html":'));
-  console.log(chalk.yellow('   • DELETE the value completely'));
-  console.log(chalk.yellow('   • Leave it EMPTY'));
-  console.log(chalk.yellow('   • Click SAVE\n'));
-  
-  console.log(chalk.bgRed.white.bold(' Failure to do this will cause deployment errors! '));
-  console.log();
-  console.log(chalk.yellow('🔐 For Public Access:'));
-  console.log(chalk.white('1. Navigate to Project Settings > General'));
-  console.log(chalk.white('2. Under "Security", find "Deployment Protection"'));
-  console.log(chalk.white('3. Set "Deployment Protection" to ') + chalk.yellow.bold('Disabled'));
-  console.log();
-  console.log(chalk.cyan('Dashboard URL: https://vercel.com/dashboard'));
+  // Post-setup reminder
+  console.log(chalk.yellow('\n📝 Quick Setup Check:'));
+  console.log(chalk.gray(`1. Visit: https://vercel.com/${answers.projectName}/settings`));
+  console.log(chalk.gray('2. Under "Build & Development Settings":'));
+  console.log(chalk.gray('   - Root Directory should be ') + chalk.green('empty'));
+  console.log(chalk.gray('   - If it shows "html", delete it'));
   console.log();
   
+  if (answers.publicAccess) {
+    console.log(chalk.gray('3. For public access, disable "Deployment Protection"'));
+    console.log();
+  }
+  
   // Add .vercel to .gitignore if not already there
   const gitignorePath = path.join(process.cwd(), '.gitignore');
   if (fs.existsSync(gitignorePath)) {
@@ -276,14 +230,10 @@ async function deployToVercel(config, isProd = false) {
           ]
         }
       ],
-      "routes": [
+      "rewrites": [
         {
-          "handle": "filesystem"
-        },
-        {
-          "src": "/(.*)",
-          "status": 404,
-          "dest": "/404.html"
+          "source": "/(.*)",
+          "destination": "/404.html"
         }
       ]
     };
@@ -466,33 +416,14 @@ 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
-  console.log(chalk.blue('\n📁 Deployment preparation - index.html check:'));
   const indexPath = path.join(outputDir, 'index.html');
   const readmePath = path.join(outputDir, 'README.html');
   
-  console.log(chalk.gray(`  - Output directory: ${outputDir}`));
-  console.log(chalk.gray(`  - Output dir exists: ${fs.existsSync(outputDir)}`));
-  
-  if (fs.existsSync(outputDir)) {
-    const files = fs.readdirSync(outputDir);
-    const htmlFiles = files.filter(f => f.endsWith('.html'));
-    console.log(chalk.gray(`  - Total files: ${files.length}`));
-    console.log(chalk.gray(`  - HTML files: [${htmlFiles.slice(0, 5).join(', ')}${htmlFiles.length > 5 ? '...' : ''}]`));
-  }
-  
-  console.log(chalk.gray(`  - Checking index.html: ${fs.existsSync(indexPath) ? 'exists' : 'missing'}`));
-  console.log(chalk.gray(`  - Index path: ${indexPath}`));
-  
   // Check if we need to create/replace index.html
   let shouldCreateIndex = false;
   
   if (!fs.existsSync(indexPath)) {
-    console.log(chalk.yellow('  ⚠️  index.html is missing, attempting to create...'));
     shouldCreateIndex = true;
   } else {
     // Check if existing index.html needs replacement
@@ -500,47 +431,25 @@ async function prepareDeployment(config) {
     const indexContent = fs.readFileSync(indexPath, 'utf8');
     
     if (indexStats.size < 3000 || (indexContent.includes('<title>Documentation</title>') && indexContent.includes('<ul>') && !indexContent.includes('class="navigation"'))) {
-      console.log(chalk.yellow(`  ⚠️  Existing index.html appears to be a directory listing (${indexStats.size} bytes), will replace`));
       shouldCreateIndex = true;
     } else if (!indexContent.includes('@knowcode/doc-builder')) {
-      console.log(chalk.yellow('  ⚠️  Existing index.html was not created by doc-builder, will replace'));
       shouldCreateIndex = true;
     }
   }
   
   if (shouldCreateIndex) {
-    console.log(chalk.gray(`  - Checking README.html: ${fs.existsSync(readmePath) ? 'exists' : 'missing'}`));
-    console.log(chalk.gray(`  - README path: ${readmePath}`));
+    // Check for README.html
     
     if (fs.existsSync(readmePath)) {
       // Copy README.html to index.html for proper root page
-      console.log(chalk.blue('  → Copying README.html to index.html...'));
       try {
         fs.copyFileSync(readmePath, indexPath);
-        console.log(chalk.green('  ✅ Successfully copied README.html to index.html'));
-        
-        // Verify the copy
-        if (fs.existsSync(indexPath)) {
-          const readmeStats = fs.statSync(readmePath);
-          const indexStats = fs.statSync(indexPath);
-          console.log(chalk.gray(`  - README.html size: ${readmeStats.size} bytes`));
-          console.log(chalk.gray(`  - index.html size: ${indexStats.size} bytes`));
-          
-          if (readmeStats.size === indexStats.size) {
-            console.log(chalk.green('  ✅ File sizes match - copy successful'));
-          } else {
-            console.log(chalk.yellow('  ⚠️  File sizes do not match!'));
-          }
-        } else {
-          console.log(chalk.red('  ❌ ERROR: index.html was not created after copy!'));
-        }
       } catch (error) {
-        console.log(chalk.red(`  ❌ ERROR copying file: ${error.message}`));
-        console.log(chalk.red(`  - Error stack: ${error.stack}`));
+        console.error(chalk.red(`Error creating index.html: ${error.message}`));
       }
     } else {
       // 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...'));
+      // No README.html, look for other HTML files
       
       // Find first available HTML file
       const htmlFiles = fs.readdirSync(outputDir)
@@ -550,7 +459,7 @@ async function prepareDeployment(config) {
       if (htmlFiles.length > 0) {
         // Redirect to first HTML file
         const firstFile = htmlFiles[0];
-        console.log(chalk.green(`✅ Creating index.html redirect to ${firstFile}`));
+        // Create index.html redirect
         const redirectIndex = `<!DOCTYPE html>
 <html>
 <head>
@@ -569,48 +478,27 @@ async function prepareDeployment(config) {
 </body>
 </html>`;
         fs.writeFileSync(indexPath, redirectIndex);
-        console.log(chalk.green(`✅ Created index.html redirect to ${firstFile}`));
+        // Created redirect
       } 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'));
+        console.error(chalk.red('No HTML files found. 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'));
+        // Created fallback index.html
       }
     }
   } else {
-    console.log(chalk.gray('  ✓ index.html already exists and appears valid'));
-    const stats = fs.statSync(indexPath);
-    console.log(chalk.gray(`  - Keeping existing index.html (${stats.size} bytes)`));
+    // index.html already exists and is valid
   }
   
-  // Final check - log what files exist
-  console.log(chalk.blue('\n📁 Final deployment state:'));
-  
-  // Double-check index.html one more time
+  // Final check
   const finalIndexExists = fs.existsSync(indexPath);
-  console.log(chalk[finalIndexExists ? 'green' : 'red'](`  - index.html: ${finalIndexExists ? 'EXISTS' : 'MISSING'}`));
-  
-  if (finalIndexExists) {
-    const stats = fs.statSync(indexPath);
-    console.log(chalk.gray(`  - index.html size: ${stats.size} bytes`));
-    console.log(chalk.gray(`  - index.html modified: ${stats.mtime.toISOString()}`));
-  }
-  
-  const finalFiles = fs.readdirSync(outputDir)
-    .filter(file => file.endsWith('.html'))
-    .slice(0, 5); // Show first 5 HTML files
-  console.log(chalk.gray(`\n  HTML files in ${outputDir}:`));
-  finalFiles.forEach(file => {
-    const size = fs.statSync(path.join(outputDir, file)).size;
-    console.log(chalk.gray(`  - ${file} (${size} bytes)`));
-  });
-  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`));
+  if (!finalIndexExists) {
+    console.error(chalk.red('Failed to create index.html'));
+    throw new Error('Deployment preparation failed');
   }
 }
 

package/package.json

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