@knowcode/doc-builder 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.3] - 2025-01-19
+
+### Fixed
+- Fixed "path argument must be string" error in deploy command
+- Improved Vercel CLI detection with helpful installation instructions
+- Made config loading more lenient for missing directories
+- Auto-build documentation if not already built before deployment
+- Better error messages with stack traces for debugging
+
+### Added
+- Automatic preparation of deployment files (index.html redirect)
+- Check for Vercel CLI before attempting deployment
+- Build documentation automatically if output directory doesn't exist
+- More robust vercel.json generation for static sites
+
+## [1.0.2] - 2025-01-19
+
+### Fixed
+- Fixed remaining JUNO references in CLI help text
+- Enhanced help documentation with detailed Vercel CLI setup instructions
+- Added comprehensive deployment troubleshooting guide
+- Improved Quick Start section with step-by-step instructions
+- Added "What gets created" explanations for init command
+
+### Added
+- Requirements section in main help
+- Example for creating docs from scratch
+- Vercel installation options (npm and Homebrew)
+- Clear instructions for disabling Vercel deployment protection
+
 ## [1.0.1] - 2025-01-19
 
 ### Fixed

package/cli.js

@@ -8,7 +8,7 @@ const fs = require('fs-extra');
 const path = require('path');
 const { build } = require('./lib/builder');
 const { startDevServer } = require('./lib/dev-server');
-const { deployToVercel, setupVercelProject } = require('./lib/deploy');
+const { deployToVercel, setupVercelProject, prepareDeployment } = require('./lib/deploy');
 const { loadConfig, createDefaultConfig } = require('./lib/config');
 const { execSync } = require('child_process');
 
@@ -25,7 +25,7 @@ program
   .description(packageJson.description)
   .version(packageJson.version)
   .addHelpText('before', `
-${chalk.cyan('🚀 @juno/doc-builder')} - Transform your markdown into beautiful documentation sites
+${chalk.cyan('🚀 @knowcode/doc-builder')} - Transform your markdown into beautiful documentation sites
 
 ${chalk.yellow('What it does:')}
   • Converts markdown files to static HTML with a beautiful Notion-inspired theme
@@ -34,10 +34,24 @@ ${chalk.yellow('What it does:')}
   • Deploys to Vercel with one command (zero configuration)
   • Optional authentication to protect private documentation
 
+${chalk.yellow('Requirements:')}
+  • Node.js 14+ installed
+  • A ${chalk.cyan('docs/')} folder with markdown files (or specify custom folder)
+  • Vercel CLI for deployment (optional)
+
 ${chalk.yellow('Quick Start:')}
-  ${chalk.gray('$')} npx @juno/doc-builder              ${chalk.gray('# Build and deploy to Vercel')}
-  ${chalk.gray('$')} npx @juno/doc-builder build        ${chalk.gray('# Build HTML files only')}
-  ${chalk.gray('$')} npx @juno/doc-builder dev          ${chalk.gray('# Start development server')}
+  ${chalk.cyan('1. Create your docs:')}
+     ${chalk.gray('$')} mkdir docs
+     ${chalk.gray('$')} echo "# My Documentation" > docs/README.md
+  
+  ${chalk.cyan('2. Build and deploy:')}
+     ${chalk.gray('$')} npx @knowcode/doc-builder              ${chalk.gray('# Build and deploy to Vercel')}
+     ${chalk.gray('   or')}
+     ${chalk.gray('$')} npx @knowcode/doc-builder build        ${chalk.gray('# Build HTML files only')}
+     ${chalk.gray('$')} npx @knowcode/doc-builder dev          ${chalk.gray('# Start development server')}
+
+${chalk.yellow('No docs folder yet?')}
+  ${chalk.gray('$')} npx @knowcode/doc-builder init --example  ${chalk.gray('# Create example docs')}
   `);
 
 // Build command
@@ -113,19 +127,73 @@ ${chalk.yellow('Examples:')}
   ${chalk.gray('$')} doc-builder deploy --prod          ${chalk.gray('# Deploy to production')}
   ${chalk.gray('$')} doc-builder deploy --no-build      ${chalk.gray('# Deploy existing build')}
 
-${chalk.yellow('First-time setup:')}
-  The tool will guide you through:
-  1. Installing Vercel CLI (if needed)
-  2. Creating a new Vercel project
-  3. Configuring deployment settings
+${chalk.yellow('First-time Vercel Setup:')}
+  
+  ${chalk.cyan('1. Install Vercel CLI:')}
+     ${chalk.gray('$')} npm install -g vercel
+     ${chalk.gray('   or')}
+     ${chalk.gray('$')} brew install vercel        ${chalk.gray('# macOS with Homebrew')}
+  
+  ${chalk.cyan('2. Login to Vercel:')}
+     ${chalk.gray('$')} vercel login
+     ${chalk.gray('   This will open your browser to authenticate')}
   
-${chalk.yellow('Important:')} After deployment, disable Vercel Authentication in project settings for public docs.
+  ${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
+  
+  ${chalk.cyan('4. Configure Access (Important!):')} 
+     After deployment, go to your Vercel dashboard:
+     • Navigate to Project Settings → General
+     • Under "Deployment Protection", set to ${chalk.yellow('Disabled')}
+     • This allows public access to your docs
+     
+${chalk.yellow('Subsequent Deployments:')}
+  ${chalk.gray('$')} npx @knowcode/doc-builder          ${chalk.gray('# Deploy preview')}
+  ${chalk.gray('$')} npx @knowcode/doc-builder deploy --prod  ${chalk.gray('# Deploy to production')}
+
+${chalk.yellow('Troubleshooting:')}
+  • ${chalk.cyan('Command not found:')} Install Vercel CLI globally
+  • ${chalk.cyan('Not authenticated:')} Run ${chalk.gray('vercel login')}
+  • ${chalk.cyan('Project not linked:')} Delete ${chalk.gray('.vercel')} folder and redeploy
 `)
   .action(async (options) => {
     const spinner = ora('Deploying to Vercel...').start();
     
     try {
-      const config = await loadConfig(options.config, options);
+      const config = await loadConfig(options.config || 'doc-builder.config.js', options);
+      
+      // First check if Vercel CLI is installed
+      try {
+        execSync('vercel --version', { stdio: 'ignore' });
+      } catch (vercelError) {
+        spinner.fail('Vercel CLI not found');
+        console.log(chalk.yellow('\n📦 Vercel CLI is required for deployment\n'));
+        console.log(chalk.cyan('Install it with one of these commands:'));
+        console.log(chalk.gray('  npm install -g vercel'));
+        console.log(chalk.gray('  yarn global add vercel'));
+        console.log(chalk.gray('  brew install vercel     # macOS\n'));
+        console.log(chalk.yellow('Then run deployment again:'));
+        console.log(chalk.gray('  npx @knowcode/doc-builder deploy\n'));
+        process.exit(1);
+      }
+      
+      // Check if we need to build first
+      const outputPath = path.join(process.cwd(), config.outputDir || 'html');
+      if (!fs.existsSync(outputPath) || !options.noBuild) {
+        spinner.stop();
+        console.log(chalk.blue('\n📦 Building documentation first...\n'));
+        await build(config);
+        spinner.start('Deploying to Vercel...');
+      }
+      
+      // Prepare deployment files
+      await prepareDeployment(config);
       
       // Check if this is the first deployment
       const vercelConfigPath = path.join(process.cwd(), '.vercel', 'project.json');
@@ -155,6 +223,9 @@ ${chalk.yellow('Important:')} After deployment, disable Vercel Authentication in
     } catch (error) {
       spinner.fail('Deployment failed');
       console.error(chalk.red(error.message));
+      if (error.stack) {
+        console.error(chalk.gray(error.stack));
+      }
       process.exit(1);
     }
   });
@@ -169,6 +240,19 @@ program
 ${chalk.yellow('Examples:')}
   ${chalk.gray('$')} doc-builder init --config          ${chalk.gray('# Create doc-builder.config.js')}
   ${chalk.gray('$')} doc-builder init --example         ${chalk.gray('# Create example docs folder')}
+  ${chalk.gray('$')} doc-builder init --example --config ${chalk.gray('# Create both')}
+
+${chalk.yellow('What gets created:')}
+  ${chalk.cyan('--example:')} Creates a docs/ folder with:
+    • README.md with welcome message and mermaid diagram
+    • getting-started.md with setup instructions
+    • guides/configuration.md with config options
+  
+  ${chalk.cyan('--config:')} Creates doc-builder.config.js with:
+    • Site name and description
+    • Feature toggles (auth, dark mode, etc.)
+    • Directory paths
+    • Authentication settings
 `)
   .action(async (options) => {
     if (options.config) {

package/lib/config.js

@@ -188,10 +188,12 @@ async function loadConfig(configPath, options = {}) {
     }
   }
   
-  // Validate paths
+  // Validate paths - but be lenient for deploy command
   const docsPath = path.join(process.cwd(), config.docsDir);
   if (!fs.existsSync(docsPath)) {
-    throw new Error(`Documentation directory not found: ${config.docsDir}`);
+    console.warn(chalk.yellow(`Warning: Documentation directory not found: ${config.docsDir}`));
+    console.log(chalk.gray(`Create it with: mkdir ${config.docsDir} && echo "# Documentation" > ${config.docsDir}/README.md`));
+    // Don't throw error - let commands handle missing directories appropriately
   }
   
   return config;

package/lib/deploy.js

@@ -51,10 +51,10 @@ async function setupVercelProject(config) {
   if (!fs.existsSync(vercelConfigPath)) {
     const vercelConfig = {
       outputDirectory: config.outputDir || 'html',
-      framework: answers.framework === 'other' ? null : answers.framework,
-      buildCommand: "npm run build:docs",
-      devCommand: "npm run dev:docs",
-      installCommand: "npm install",
+      framework: null,  // Static HTML
+      buildCommand: "", // No build needed - we already built
+      devCommand: "",   // No dev command
+      installCommand: "", // No install needed
       public: answers.publicAccess
     };
     

package/package.json

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