@knowcode/doc-builder 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.0.5] - 2025-01-19
+
+### Fixed
+- Fixed "vercel.json file should be inside of the provided root directory" error
+- Deploy commands now run from the output directory (html/) instead of project root
+- Vercel link command runs from correct directory during setup
+- vercel.json is now created in the output directory where it belongs
+
+### Changed
+- Simplified vercel.json configuration for static sites
+- Updated deployment flow to work correctly with Vercel's expectations
+- Vercel project detection now checks in output directory
+
+## [1.0.4] - 2025-01-19
+
+### Added
+- Comprehensive Vercel CLI prompt explanations in help text
+- Step-by-step answers for all Vercel setup questions
+- Hints in prompts to guide users through setup
+- Pre-deployment guidance showing what Vercel will ask
+- Better project name sanitization for Vercel URLs
+
+### Improved
+- More detailed deployment help with exact answers to provide
+- Clearer instructions for first-time vs. subsequent deployments
+- Visual question/answer format in help documentation
+
 ## [1.0.3] - 2025-01-19
 
 ### Fixed

package/cli.js

@@ -141,11 +141,35 @@ ${chalk.yellow('First-time Vercel Setup:')}
   ${chalk.cyan('3. Run doc-builder deploy:')}
      ${chalk.gray('$')} npx @knowcode/doc-builder deploy
      
-     The tool will:
-     • Create a new Vercel project
-     • Link it to your documentation
-     • Deploy your site
-     • Provide you with a URL
+     You'll be asked several questions:
+     
+     ${chalk.green('Q: Would you like to set up a new Vercel project?')}
+     → Answer: ${chalk.yellow('Yes')} (first time only)
+     
+     ${chalk.green('Q: What is your project name?')}
+     → Answer: ${chalk.yellow('Your project name')} (e.g., "my-docs" or "gasworld")
+     
+     ${chalk.green('Q: Which framework preset?')}
+     → Answer: ${chalk.yellow('Other (Static HTML)')} (always choose this)
+     
+     ${chalk.green('Q: Make the deployment publicly accessible?')}
+     → Answer: ${chalk.yellow('Yes')} for public docs, ${chalk.yellow('No')} for private
+     
+     ${chalk.gray('Then Vercel CLI will ask:')}
+     
+     ${chalk.green('Q: Set up [your directory]?')}
+     → Answer: ${chalk.yellow('Yes')}
+     
+     ${chalk.green('Q: Which scope should contain your project?')}
+     → Answer: ${chalk.yellow('Select your account')} (usually your username)
+     
+     ${chalk.green('Q: Link to existing project?')}
+     → Answer: ${chalk.yellow('No')} (first time), ${chalk.yellow('Yes')} (if redeploying)
+     
+     ${chalk.gray('Note: Vercel will auto-detect that we\'re deploying from the output directory')}
+     
+     ${chalk.green('Q: Want to modify these settings?')}
+     → Answer: ${chalk.yellow('No')} (doc-builder handles this)
   
   ${chalk.cyan('4. Configure Access (Important!):')} 
      After deployment, go to your Vercel dashboard:
@@ -196,8 +220,8 @@ ${chalk.yellow('Troubleshooting:')}
       await prepareDeployment(config);
       
       // Check if this is the first deployment
-      const vercelConfigPath = path.join(process.cwd(), '.vercel', 'project.json');
-      if (!fs.existsSync(vercelConfigPath)) {
+      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'));
         
@@ -330,8 +354,8 @@ program
       const deploySpinner = ora('Deploying to Vercel...').start();
       
       // Check if this is the first deployment
-      const vercelConfigPath = path.join(process.cwd(), '.vercel', 'project.json');
-      if (!fs.existsSync(vercelConfigPath)) {
+      const vercelProjectPath = path.join(outputPath, '.vercel', 'project.json');
+      if (!fs.existsSync(vercelProjectPath)) {
         deploySpinner.stop();
         console.log(chalk.yellow('\n🚀 First time deploying to Vercel!\n'));
         

package/lib/deploy.js

@@ -25,7 +25,8 @@ async function setupVercelProject(config) {
       type: 'text',
       name: 'projectName',
       message: 'What is your project name?',
-      initial: config.siteName || 'my-docs'
+      initial: config.siteName.toLowerCase().replace(/[^a-z0-9-]/g, '-') || 'my-docs',
+      hint: 'This will be your URL: project-name.vercel.app'
     },
     {
       type: 'select',
@@ -36,37 +37,52 @@ async function setupVercelProject(config) {
         { title: 'Next.js', value: 'nextjs' },
         { title: 'Vite', value: 'vite' }
       ],
-      initial: 0
+      initial: 0,
+      hint: 'Choose "Other (Static HTML)" for doc-builder'
     },
     {
       type: 'confirm',
       name: 'publicAccess',
       message: 'Make the deployment publicly accessible?',
-      initial: true
+      initial: true,
+      hint: 'Choose Yes for public docs, No for team-only access'
     }
   ]);
   
-  // Create vercel.json if it doesn't exist
-  const vercelConfigPath = path.join(process.cwd(), 'vercel.json');
-  if (!fs.existsSync(vercelConfigPath)) {
-    const vercelConfig = {
-      outputDirectory: config.outputDir || 'html',
-      framework: null,  // Static HTML
-      buildCommand: "", // No build needed - we already built
-      devCommand: "",   // No dev command
-      installCommand: "", // No install needed
-      public: answers.publicAccess
-    };
-    
-    fs.writeJsonSync(vercelConfigPath, vercelConfig, { spaces: 2 });
-    console.log(chalk.green('✅ Created vercel.json'));
+  // Create vercel.json in the output directory
+  const outputDir = path.join(process.cwd(), config.outputDir || 'html');
+  const vercelConfigPath = path.join(outputDir, 'vercel.json');
+  
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
   }
   
+  // Create vercel.json for static site
+  const vercelConfig = {
+    buildCommand: false,
+    outputDirectory: ".",
+    framework: null
+  };
+  
+  fs.writeJsonSync(vercelConfigPath, vercelConfig, { spaces: 2 });
+  console.log(chalk.green(`✅ Created vercel.json in ${config.outputDir || 'html'} directory`));
+  
   // Run Vercel setup
   console.log(chalk.blue('\n🔗 Linking to Vercel...\n'));
+  console.log(chalk.yellow('📝 Vercel will now ask additional questions:\n'));
+  console.log(chalk.gray('• Set up and deploy? → Yes'));
+  console.log(chalk.gray('• Which scope? → Select your account'));
+  console.log(chalk.gray('• Link to existing? → No (first time)'));
+  console.log(chalk.gray('• Project name? → ' + answers.projectName));
+  console.log(chalk.gray('• Override settings? → No\n'));
   
   try {
-    execSync('vercel link', { stdio: 'inherit' });
+    // Run vercel link from the output directory
+    execSync('vercel link', { 
+      stdio: 'inherit',
+      cwd: outputDir
+    });
   } catch (error) {
     console.error(chalk.red('Failed to link Vercel project'));
     process.exit(1);
@@ -104,13 +120,24 @@ async function deployToVercel(config, isProd = false) {
     throw new Error(`Output directory ${outputPath} does not exist. Run 'doc-builder build' first.`);
   }
   
+  // Create vercel.json in output directory for deployment
+  const vercelConfigPath = path.join(outputPath, 'vercel.json');
+  if (!fs.existsSync(vercelConfigPath)) {
+    const vercelConfig = {
+      buildCommand: false,
+      outputDirectory: ".",
+      framework: null
+    };
+    fs.writeJsonSync(vercelConfigPath, vercelConfig, { spaces: 2 });
+  }
+  
   // Deploy command
   const deployCmd = isProd ? 'vercel --prod' : 'vercel';
   
   try {
-    // Run deployment and capture output
+    // Run deployment from the output directory
     const output = execSync(deployCmd, { 
-      cwd: process.cwd(),
+      cwd: outputPath,
       encoding: 'utf8'
     });
     

package/package.json

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