@knowcode/doc-builder 1.2.11 → 1.3.0

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.3.0] - 2025-07-19
+
+### BREAKING CHANGE
+- **Default behavior changed**: Running `npx @knowcode/doc-builder` without arguments now shows help instead of building and deploying
+- To deploy, explicitly use: `npx @knowcode/doc-builder deploy`
+
+### Changed
+- Updated TL;DR in help text to show `npx @knowcode/doc-builder deploy`
+- Reordered commands in help to show deploy as the recommended action
+- Updated README.md to reflect the new default behavior
+
+### Why this change?
+- Prevents accidental deployments when users just want to see available commands
+- Makes the tool more predictable - no actions without explicit commands
+- Aligns with standard CLI tool behavior
+
+## [1.2.12] - 2025-07-19
+
+### Added
+- Support for alternative config file formats (site.title → siteName mapping)
+- Support for input/output directory mapping in config files
+- Debug logging for site name configuration
+
+### Fixed
+- Header now properly displays the project name from config instead of generic "Documentation"
+- Config loader now handles both old and new config formats
+
+### Documentation
+- Updated GasWorld config to use correct format with siteName: 'GasWorld'
+
 ## [1.2.11] - 2025-07-19
 
 ### Fixed

package/README.md

@@ -31,17 +31,15 @@ Perfect for project documentation, API references, knowledge bases, or any conte
 No installation needed! Just run:
 
 ```bash
-# Build and deploy to Vercel (default action)
-npx @knowcode/doc-builder
+# Build and deploy to Vercel
+npx @knowcode/doc-builder deploy
 
-# Or use specific commands:
+# Other available commands:
 npx @knowcode/doc-builder build   # Build HTML files only
 npx @knowcode/doc-builder dev      # Start development server
-npx @knowcode/doc-builder deploy   # Deploy to Vercel
+npx @knowcode/doc-builder          # Show help (default behavior)
 ```
 
-The default action (no command specified) will build your documentation and deploy it to Vercel.
-
 ## Installation (Optional)
 
 For faster execution and offline use:

package/cli.js

@@ -15,11 +15,6 @@ const { execSync } = require('child_process');
 // Package info
 const packageJson = require('./package.json');
 
-// Default to build command if no args provided
-if (process.argv.length === 2) {
-  process.argv.push('build');
-}
-
 program
   .name('doc-builder')
   .description(packageJson.description)
@@ -27,7 +22,7 @@ program
   .addHelpText('before', `
 ${chalk.cyan('🚀 @knowcode/doc-builder')} - Transform your markdown into beautiful documentation sites
 
-${chalk.bgGreen.black(' TL;DR ')} ${chalk.green('Just run:')} ${chalk.cyan.bold('npx @knowcode/doc-builder')} ${chalk.green('→ Your docs are live on Vercel!')}
+${chalk.bgGreen.black(' TL;DR ')} ${chalk.green('Just run:')} ${chalk.cyan.bold('npx @knowcode/doc-builder deploy')} ${chalk.green('→ Your docs are live on Vercel!')}
 
 ${chalk.gray('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}
 
@@ -36,7 +31,7 @@ ${chalk.yellow('What it does:')}
   • Automatically generates navigation from your folder structure
   • Supports mermaid diagrams, syntax highlighting, and dark mode
   • Deploys to Vercel with one command (zero configuration)
-  • ${chalk.green.bold('NEW:')} Deploys directly to production by default (v1.1.0+)
+  • ${chalk.green.bold('NEW:')} Shows help by default, use 'deploy' to publish (v1.3.0+)
   • Optional authentication to protect private documentation
 
 ${chalk.yellow('Requirements:')}
@@ -50,8 +45,8 @@ ${chalk.yellow('Quick Start:')}
      ${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 production')}
-     ${chalk.gray('   or')}
+     ${chalk.gray('$')} npx @knowcode/doc-builder              ${chalk.gray('# Show help and available commands')}
+     ${chalk.gray('$')} npx @knowcode/doc-builder deploy       ${chalk.gray('# Build and deploy to production')}
      ${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')}
 
@@ -186,10 +181,10 @@ ${chalk.yellow('First-time Vercel Setup:')}
      • Under "Deployment Protection", set to ${chalk.yellow('Disabled')}
      • This allows public access to your docs
      
-${chalk.yellow('Deployment Behavior (v1.1.0+):')}
+${chalk.yellow('Deployment Behavior:')}
   ${chalk.green.bold('🎯 DEFAULT: All deployments go to PRODUCTION')}
   
-  ${chalk.gray('$')} npx @knowcode/doc-builder          ${chalk.gray('# → yourdocs.vercel.app')}
+  ${chalk.gray('$')} npx @knowcode/doc-builder          ${chalk.gray('# → Shows help (v1.3.0+)')}
   ${chalk.gray('$')} npx @knowcode/doc-builder deploy   ${chalk.gray('# → yourdocs.vercel.app')}
   ${chalk.gray('$')} npx @knowcode/doc-builder deploy --no-prod  ${chalk.gray('# → preview URL only')}
 
@@ -476,77 +471,11 @@ ${chalk.yellow('What gets created:')}
     }
   });
 
-// Add a default command handler for when doc-builder is run without arguments
-program
-  .action(async () => {
-    // Default action is build + deploy to production
-    console.log(chalk.cyan('\n🚀 Building and deploying your documentation to production...\n'));
-    
-    try {
-      // Build first
-      const config = await loadConfig('doc-builder.config.js', { legacy: true });
-      const buildSpinner = ora('Building documentation...').start();
-      await build(config);
-      buildSpinner.succeed('Documentation built successfully!');
-      
-      // Then deploy
-      const deploySpinner = ora('Deploying to Vercel...').start();
-      
-      // Check if this is the first deployment
-      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'));
-        
-        // 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'));
-        
-        const setupConfirm = await prompts({
-          type: 'confirm',
-          name: 'value',
-          message: 'Would you like to set up a new Vercel project?',
-          initial: true
-        });
-        
-        if (setupConfirm.value) {
-          await setupVercelProject(config);
-        } else {
-          console.log(chalk.gray('\nTo deploy manually, run: vercel'));
-          console.log(chalk.gray('To skip deployment, run: doc-builder build\n'));
-          process.exit(0);
-        }
-        deploySpinner.start('Deploying to Vercel...');
-      }
-      
-      // Default to production deployment
-      const url = await deployToVercel(config, true);
-      deploySpinner.succeed(`Deployed successfully!`);
-      
-      // Extract project name from URL
-      const projectName = url.match(/https:\/\/([^-]+)/)?.[1] || 'your-project';
-      
-      console.log(chalk.green('\n✅ Deployment Complete!\n'));
-      console.log(chalk.yellow('🌐 Your documentation is live at:'));
-      console.log(chalk.cyan.bold(`   ${projectName}.vercel.app`) + chalk.gray(' (Production URL - share this!)'));
-      console.log();
-      console.log(chalk.gray('This deployment also created a unique preview URL:'));
-      console.log(chalk.gray(`   ${url}`));
-      console.log(chalk.gray('   (This URL is specific to this deployment)'));
-      console.log();
-      
-    } catch (error) {
-      console.error(chalk.red('\nError: ' + error.message));
-      console.log(chalk.gray('\nTo build without deploying, run: doc-builder build'));
-      process.exit(1);
-    }
-  });
-
 // Parse arguments
-program.parse(process.argv);
+program.parse(process.argv);
+
+// Show help if no command was provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+  process.exit(0);
+}

package/lib/config.js

@@ -153,6 +153,27 @@ async function loadConfig(configPath, options = {}) {
     try {
       const customConfig = require(customConfigPath);
       config = { ...config, ...customConfig };
+      
+      // Handle alternative config formats
+      if (customConfig.site) {
+        // Map site.title to siteName
+        if (customConfig.site.title) {
+          config.siteName = customConfig.site.title;
+          console.log(chalk.gray(`  Using site name: ${config.siteName}`));
+        }
+        if (customConfig.site.description) {
+          config.siteDescription = customConfig.site.description;
+        }
+      }
+      
+      // Map input/output to docsDir/outputDir
+      if (customConfig.input) {
+        config.docsDir = customConfig.input;
+      }
+      if (customConfig.output) {
+        config.outputDir = customConfig.output;
+      }
+      
       console.log(chalk.gray(`Loaded config from ${configPath}`));
     } catch (error) {
       console.warn(chalk.yellow(`Warning: Failed to load config file: ${error.message}`));

package/package.json

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

package/scripts/npx-runner.js

@@ -9,14 +9,14 @@ const { execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
-// Get the command from arguments
-const [,, command = 'build', ...args] = process.argv;
+// Get the command from arguments - no default command
+const [,, ...args] = process.argv;
 
 // Path to the actual CLI
 const cliPath = path.join(__dirname, '..', 'cli.js');
 
-// Build the command
-const fullCommand = `node "${cliPath}" ${command} ${args.join(' ')}`;
+// Build the command - pass all arguments through
+const fullCommand = `node "${cliPath}" ${args.join(' ')}`;
 
 try {
   // Execute the CLI with stdio inherited to preserve colors and interactivity